crypto: Doc link fixes

2 files changed, 68 insertions, 29 deletions

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 751cf9d1fc..d1d1252f29 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -678,7 +678,8 @@
 	</p>
 	<p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>. For decryption, set it to <c>false</c>.
 	</p>
-	<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
+	<p>See <seealso marker="crypto:new_api#examples-of-crypto_init-4-and-crypto_update-2">
+	examples in the User's Guide.</seealso>
 	</p>
       </desc>
     </func>
@@ -696,7 +697,8 @@
 	or
 	<seealso marker="crypto#crypto_init/4">crypto_init/4</seealso>.
 	</p>
-	<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
+	<p>See <seealso marker="crypto:new_api#examples-of-crypto_init-4-and-crypto_update-2">
+	examples in the User's Guide.</seealso>
 	</p>
       </desc>
     </func>
@@ -712,8 +714,6 @@
 	</p>
 	<p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>. For decryption, set it to <c>false</c>.
 	</p>
-	<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
-	</p>
       </desc>
     </func>
 
@@ -726,8 +726,6 @@
 	The <c>State</c> should be created with
 	<seealso marker="crypto#crypto_dyn_iv_init/3">crypto_dyn_iv_init/3</seealso>.
 	</p>
-	<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
-	</p>
       </desc>
     </func>
 
@@ -744,11 +742,11 @@
       <fsummary>Do a complete encrypt or decrypt of the full text</fsummary>
       <desc>
 	<p>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>.
-	Do a complete encrypt or decrypt of the full text.
+	Do a complete encrypt or decrypt of the full text in the argument <c>Data</c>.
 	</p>
 	<p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>. For decryption, set it to <c>false</c>.
 	</p>
-	<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
+	<p>See <seealso marker="crypto:new_api#example-of-crypto_one_time-5">examples in the User's Guide.</seealso>
 	</p>
       </desc>
     </func>
@@ -768,7 +766,7 @@
 	<p>For decryption, set the <c>EncryptFlag</c> to <c>false</c> and put the tag to be checked
 	in the argument	<c>TagOrTagLength</c>.
 	</p>
-	<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
+	<p>See <seealso marker="crypto:new_api#example-of-crypto_one_time_aead-6">examples in the User's Guide.</seealso>
 	</p>
       </desc>
     </func>
diff --git a/lib/crypto/doc/src/new_api.xml b/lib/crypto/doc/src/new_api.xml
index 58ace97554..bd2334ac9f 100644
--- a/lib/crypto/doc/src/new_api.xml
+++ b/lib/crypto/doc/src/new_api.xml
@@ -59,9 +59,9 @@
       <item><seealso marker="crypto#stream_init-2">stream_init/3</seealso></item>
       <item><seealso marker="crypto#stream_encrypt-2">stream_encrypt/2</seealso></item>
       <item><seealso marker="crypto#stream_decrypt-2">stream_decrypt/2</seealso></item>
-      <item><seealso marker="crypto#supports-0">suppports/0</seealso></item>
+      <item><seealso marker="crypto#supports-0">supports/0</seealso></item>
     </list>
-    <p>They are not deprecated for now, but may be in a future.
+    <p>They are not deprecated for now, but may be in a future release.
     </p>
   </section>
 
@@ -76,7 +76,8 @@
       <item><seealso marker="crypto#crypto_one_time_aead/7">crypto_one_time_aead/7</seealso></item>
     </list>
     <p>In those functions the internal crypto state is first created and initialized
-    with the cipher type, the key and possibly other data. Then the data is encrypted or decrypted,
+    with the cipher type, the key and possibly other data. Then the single binary is encrypted
+    or decrypted,
     the crypto state is de-allocated and the result of the crypto operation is returned.
     </p>
     <p>The <c>crypto_one_time_aead</c> functions are for the ciphers of mode <c>ccm</c> or
@@ -114,29 +115,39 @@
 
     <section>
       <title>Examples of crypto_init/4 and crypto_update/2</title>
-      <p>Encrypting two blocks:</p>
+      <p>The functions <seealso marker="crypto#crypto_init/4">crypto_init/4</seealso>
+      and <seealso marker="crypto#crypto_update/2">crypto_update/2</seealso> are intended
+      to be used for encrypting or decrypting a sequence of blocks. First one call of
+      <c>crypto_init/4</c> initialises the crypto context. One or more calls <c>crypto_update/2</c>
+      does the actual encryption or decryption for each block.
+      </p>
+      <p>This example shows first the encryption of two blocks and then decryptions of the cipher
+      text, but divided into three blocks just to show that it is possible to divide the plain text and
+      cipher text differently for some ciphers:</p>
       <code type="erl">
 	1> crypto:start().
 	ok
 	2> Key = &lt;&lt;1:128>>.
-	2> IV = &lt;&lt;0:128>>.
-	2> StateEnc = crypto:crypto_init(aes_128_ctr, Key, IV, true). % encrypt -> true
+	&lt;&lt;0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>>
+	3> IV = &lt;&lt;0:128>>.
+	&lt;&lt;0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0>>
+	4> StateEnc = crypto:crypto_init(aes_128_ctr, Key, IV, true). % encrypt -> true
 	#Ref&lt;0.3768901617.1128660993.124047>
-	3> crypto:crypto_update(StateEnc, &lt;&lt;"First bytes">>).
+	5> crypto:crypto_update(StateEnc, &lt;&lt;"First bytes">>).
 	&lt;&lt;67,44,216,166,25,130,203,5,66,6,162>>
-	4> crypto:crypto_update(StateEnc, &lt;&lt;"Second bytes">>).
+	6> crypto:crypto_update(StateEnc, &lt;&lt;"Second bytes">>).
 	&lt;&lt;16,79,94,115,234,197,94,253,16,144,151,41>>
-	5>
-	5> StateDec = crypto:crypto_init(aes_128_ctr, Key, IV, false). % decrypt -> false
+	7>
+	7> StateDec = crypto:crypto_init(aes_128_ctr, Key, IV, false). % decrypt -> false
 	#Ref&lt;0.3768901617.1128660994.124255>
-	6> crypto:crypto_update(StateDec, &lt;&lt;67,44,216,166,25,130,203>>).
+	8> crypto:crypto_update(StateDec, &lt;&lt;67,44,216,166,25,130,203>>).
 	&lt;&lt;"First b">>
-	7> crypto:crypto_update(StateDec, &lt;&lt;5,66,6,162,16,79,94,115,234,197,
-                                                                     94,253,16,144,151>>).
+	9> crypto:crypto_update(StateDec, &lt;&lt;5,66,6,162,16,79,94,115,234,197,
+                                            94,253,16,144,151>>).
 	&lt;&lt;"ytesSecond byte">>
-	8> crypto:crypto_update(StateDec, &lt;&lt;41>>).
+	10> crypto:crypto_update(StateDec, &lt;&lt;41>>).
 	&lt;&lt;"s">>
-	9>
+	11>
       </code>
       <p>Note that the internal data that the <c>StateEnc</c> and <c>StateDec</c> references are
       destructivly updated by the calls to <seealso marker="crypto#crypto_update/2">crypto_update/2</seealso>.
@@ -163,21 +174,51 @@
       <title>Example of crypto_one_time/5</title>
       <p>The same example as in the
       <seealso marker="#examples-of-crypto_init-4-and-crypto_update-2">previous section</seealso>,
-      but now with one call to <c>crypto_one_time/5</c>:
+      but now with one call to <seealso marker="crypto#crypto_one_time/5">crypto_one_time/5</seealso>:
       </p>
       <code>
-	2> Key = &lt;&lt;1:128>>.
+	1> Key = &lt;&lt;1:128>>.
+	&lt;&lt;0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>>
 	2> IV = &lt;&lt;0:128>>.
-	2> Txt = [&lt;&lt;"First bytes">>,&lt;&lt;"Second bytes">>],
-	2> crypto:crypto_one_time(aes_128_ctr, Key, IV, Txt, true).
+	&lt;&lt;0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0>>
+	3> Txt = [&lt;&lt;"First bytes">>,&lt;&lt;"Second bytes">>].
+	[&lt;&lt;"First bytes">>,&lt;&lt;"Second bytes">>]
+	4> crypto:crypto_one_time(aes_128_ctr, Key, IV, Txt, true).
 	&lt;&lt;67,44,216,166,25,130,203,5,66,6,162,16,79,94,115,234,
 	197,94,253,16,144,151,41>>
-	3>
+	5>
       </code>
       <p>The <c>[&lt;&lt;"First bytes">>,&lt;&lt;"Second bytes">>]</c> could of course have been one
       single binary: <c>&lt;&lt;"First bytesSecond bytes">></c>.
       </p>
     </section>
+
+    <section>
+      <title>Example of crypto_one_time_aead/6</title>
+      <p>The same example as in the
+      <seealso marker="#example-of-crypto_one_time-5">previous section</seealso>,
+      but now with one call to <seealso marker="crypto#crypto_one_time_aead/6">crypto_one_time_aead/6</seealso>:
+      </p>
+      <code>
+	1> Key = &lt;&lt;1:128>>.
+	&lt;&lt;0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>>
+	2> IV = &lt;&lt;0:128>>.
+	&lt;&lt;0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0>>
+	3> Txt = [&lt;&lt;"First bytes">>,&lt;&lt;"Second bytes">>].
+	[&lt;&lt;"First bytes">>,&lt;&lt;"Second bytes">>]
+	4> AAD = &lt;&lt;"Some bytes">>.
+	&lt;&lt;"Some bytes">>
+	5> crypto:crypto_one_time_aead(aes_128_gcm, Key, IV, Txt, AAD, true).
+	{&lt;&lt;240,130,38,96,130,241,189,52,3,190,179,213,132,1,72,
+	192,103,176,90,104,15,71,158>>,
+	&lt;&lt;131,47,45,91,142,85,9,244,21,141,214,71,31,135,2,155>>}
+	9>
+      </code>
+      <p>The <c>[&lt;&lt;"First bytes">>,&lt;&lt;"Second bytes">>]</c> could of course have been one
+      single binary: <c>&lt;&lt;"First bytesSecond bytes">></c>.
+      </p>
+    </section>
+
   </section>
 
   <section>