crypto: Modernized 'Algorithms' section in User's Guide

Adapted to the "New API" introduced in 22.0

2 files changed, 185 insertions, 86 deletions

diff --git a/lib/crypto/doc/src/algorithm_details.xml b/lib/crypto/doc/src/algorithm_details.xml
index 85ae766c35..71014764c8 100644
--- a/lib/crypto/doc/src/algorithm_details.xml
+++ b/lib/crypto/doc/src/algorithm_details.xml
@@ -37,81 +37,129 @@
 
   <section>
     <title>Ciphers</title>
+    <p>A <seealso marker="crypto#type-cipher">cipher</seealso> in the
+    <seealso marker="crypto:new_api#the-new-api">new api</seealso>
+    is categorized as either
+    <seealso marker="crypto#type-cipher_no_iv">cipher_no_iv()</seealso>,
+    <seealso marker="crypto#type-cipher_iv">cipher_iv()</seealso> or
+    <seealso marker="crypto#type-cipher_aead">cipher_aead()</seealso>.
+    The letters IV are short for <i>Initialization Vector</i> and
+    AEAD is an abreviation of <i>Authenticated Encryption with Associated Data</i>.
+    </p>
+    <p>Due to irregular naming conventions, some cipher names in the old api are
+    substitued by new names in the new api. For a list of retired names, see
+    <seealso marker="crypto:new_api#retired-cipher-names">Retired cipher names</seealso>.
+    </p>
+    <p>To dynamically check availability, check that the name in the <i>Cipher and Mode</i> column is present in the
+    list returned by <seealso marker="crypto#supports-1">crypto:supports(ciphers)</seealso>.
+    </p>
+    
     <section>
-      <title>Block Ciphers</title>
-      <p>To be used in
-      <seealso marker="crypto#block_encrypt-3">block_encrypt/3</seealso>,
-      <seealso marker="crypto#block_encrypt-4">block_encrypt/4</seealso>,
-      <seealso marker="crypto#block_decrypt-3">block_decrypt/3</seealso> and
-      <seealso marker="crypto#block_decrypt-4">block_decrypt/4</seealso>.
-      </p>
-      <p>Available in all OpenSSL compatible with Erlang CRYPTO if not disabled by configuration.
+      <title>Ciphers without an IV - cipher_no_iv()</title>
+      <p>To be used with:
       </p>
-      <p>To dynamically check availability, check that the name in the <i>Cipher and Mode</i> column is present in the
-      list returned by <seealso marker="crypto#supports-1">crypto:supports(ciphers)</seealso>.
+      <list>
+	<item><seealso marker="crypto#crypto_one_time/4">crypto_one_time/4</seealso></item>
+	<item><seealso marker="crypto#crypto_init/3">crypto_init/3</seealso></item>
+      </list>
+      <p>The ciphers are:
       </p>
       <table>
-	<row><cell><strong>Cipher and Mode</strong></cell><cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell><cell><strong>IV length</strong><br/><strong>[bytes]</strong></cell><cell><strong>Block size</strong><br/><strong>[bytes]</strong></cell></row>
-	<row><cell><c>aes_cbc</c></cell>  <cell>16, 24, 32</cell><cell>16</cell><cell>16</cell></row>
-	<row><cell><c>aes_cbc128</c></cell><cell>16</cell><cell>16</cell><cell>16</cell></row>
-	<row><cell><c>aes_cbc256</c></cell><cell>32</cell><cell>16</cell><cell>16</cell></row>
-
-	<row><cell><c>aes_cfb8</c></cell>  <cell>16, 24, 32</cell><cell>16</cell><cell>any</cell></row>
-
-	<row><cell><c>aes_ecb</c></cell><cell>16, 24, 32</cell><cell> </cell><cell>16</cell></row>
-
-	<row><cell><c>aes_ige256</c></cell><cell>16</cell><cell>32</cell><cell>16</cell></row>
-	<row><cell><c>blowfish_cbc</c></cell> <cell>4-56</cell> <cell>8</cell> <cell>8</cell></row>
-	<row><cell><c>blowfish_cfb64</c></cell> <cell>&#8805;1</cell> <cell>8</cell> <cell>any</cell></row>
-	<row><cell><c>blowfish_ecb</c></cell><cell>&#8805;1</cell><cell> </cell><cell>8</cell></row>
-	<row><cell><c>blowfish_ofb64</c></cell><cell>&#8805;1</cell><cell>8</cell><cell>any</cell></row>
-
-	<row><cell><c>des3_cbc</c><br/><i>(=DES EDE3 CBC)</i></cell><cell>[8,8,8]</cell><cell>8</cell><cell>8</cell></row>
-	<row><cell><c>des3_cfb</c><br/><i>(=DES EDE3 CFB)</i></cell><cell>[8,8,8]</cell><cell>8</cell><cell>any</cell></row>
-
-	<row><cell><c>des_cbc</c></cell><cell>8</cell><cell>8</cell> <cell>8</cell></row>
-	<row><cell><c>des_cfb</c></cell><cell>8</cell><cell>8</cell><cell>any</cell></row>
-	<row><cell><c>des_ecb</c></cell><cell>8</cell><cell> </cell><cell>8</cell></row>
-	<row><cell><c>des_ede3</c><br/><i>(=DES EDE3 CBC)</i></cell><cell>[8,8,8]</cell><cell>8</cell><cell>8</cell></row>
-	<row><cell><c>rc2_cbc</c></cell><cell>&#8805;1</cell><cell>8</cell><cell>8</cell></row>
-	<tcaption>Block cipher key lengths</tcaption>
+	<row>
+	  <cell><strong>Cipher and Mode</strong></cell>
+	  <cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell>
+	  <cell><strong>Block size</strong><br/><strong>[bytes]</strong></cell>
+	</row>
+	<row><cell><c>aes_128_ecb</c></cell>  <cell>16</cell>      <cell>16</cell></row>
+	<row><cell><c>aes_192_ecb</c></cell>  <cell>24</cell>      <cell>16</cell></row>
+	<row><cell><c>aes_256_ecb</c></cell>  <cell>32</cell>      <cell>16</cell></row>
+	<row><cell><c>blowfish_ecb</c></cell> <cell>16</cell>      <cell>&nbsp;8</cell></row>
+	<row><cell><c>des_ecb</c></cell>      <cell>&nbsp;8</cell> <cell>&nbsp;8</cell></row>
+	<row><cell><c>rc4</c></cell>          <cell>16</cell>      <cell>&nbsp;1</cell></row>
+	<tcaption>Ciphers without IV</tcaption>
       </table>
     </section>
 
     <section>
-      <title>AEAD Ciphers</title>
-      <p>To be used in <seealso marker="crypto#block_encrypt-4">block_encrypt/4</seealso> and
-      <seealso marker="crypto#block_decrypt-4">block_decrypt/4</seealso>.
+      <title>Ciphers with an IV - cipher_iv()</title>
+      <p>To be used with:
       </p>
-      <p>To dynamically check availability, check that the name in the <i>Cipher and Mode</i> column is present in the
-      list returned by <seealso marker="crypto#supports-1">crypto:supports(ciphers)</seealso>.
+      <list>
+	<item><seealso marker="crypto#crypto_one_time/5">crypto_one_time/5</seealso></item>
+	<item><seealso marker="crypto#crypto_init/4">crypto_init/4</seealso></item>
+	<item><seealso marker="crypto#crypto_dyn_iv_init/3">crypto_dyn_iv_init/3</seealso></item>
+      </list>
+      <p>The ciphers are:
       </p>
       <table>
-	<row><cell><strong>Cipher and Mode</strong></cell><cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell><cell><strong>IV length</strong><br/><strong>[bytes]</strong></cell><cell><strong>AAD length</strong><br/><strong>[bytes]</strong></cell><cell><strong>Tag length</strong><br/><strong>[bytes]</strong></cell><cell><strong>Block size</strong><br/><strong>[bytes]</strong></cell><cell><strong>Supported with</strong><br/><strong>OpenSSL versions</strong></cell></row>
-	<row><cell><c>aes_ccm</c></cell> <cell>16,24,32</cell> <cell>7-13</cell> <cell>any</cell> <cell>even 4-16<br/>default: 12</cell> <cell>any</cell><cell>&#8805;1.1.0</cell></row>
-	<row><cell><c>aes_gcm</c></cell> <cell>16,24,32</cell> <cell>&#8805;1</cell> <cell>any</cell> <cell>1-16<br/>default: 16</cell> <cell>any</cell><cell>&#8805;1.1.0</cell></row>
-	<row><cell><c>chacha20_poly1305</c></cell><cell>32</cell> <cell>1-16</cell> <cell>any</cell> <cell>16</cell> <cell>any</cell><cell>&#8805;1.1.0</cell></row>
-	<tcaption>AEAD cipher key lengths</tcaption>
+	<row>
+	  <cell><strong>Cipher and Mode</strong></cell>
+	  <cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell>
+	  <cell><strong>IV length</strong><br/><strong>[bytes]</strong></cell>
+	  <cell><strong>Block size</strong><br/><strong>[bytes]</strong></cell>
+	  <cell><strong>Limited to</strong><br/><strong>OpenSSL versions</strong></cell>
+	</row>
+	<row><cell><c>aes_128_cbc</c></cell>   <cell>16</cell>      <cell>16</cell>      <cell>16</cell>      <cell></cell></row>
+	<row><cell><c>aes_192_cbc</c></cell>   <cell>24</cell>      <cell>16</cell>      <cell>16</cell>      <cell></cell></row>
+	<row><cell><c>aes_256_cbc</c></cell>   <cell>32</cell>      <cell>16</cell>      <cell>16</cell>      <cell></cell></row>
+	<row><cell><c>aes_128_cfb8</c></cell>  <cell>16</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>aes_192_cfb8</c></cell>  <cell>24</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>aes_256_cfb8</c></cell>  <cell>32</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>aes_128_cfb128</c></cell><cell>16</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>aes_192_cfb128</c></cell><cell>24</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>aes_256_cfb128</c></cell><cell>32</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>aes_128_ctr</c></cell>   <cell>16</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>aes_192_ctr</c></cell>   <cell>24</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>aes_256_ctr</c></cell>   <cell>32</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>aes_ige256</c></cell>    <cell>16</cell>      <cell>32</cell>      <cell>16</cell>      <cell></cell></row>
+	<row><cell><c>blowfish_cbc</c></cell>  <cell>16</cell>      <cell>&nbsp;8</cell> <cell>&nbsp;8</cell> <cell></cell></row>
+	<row><cell><c>blowfish_cfb64</c></cell><cell>16</cell>      <cell>&nbsp;8</cell> <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>blowfish_ofb64</c></cell><cell>16</cell>      <cell>&nbsp;8</cell> <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>chacha20</c></cell>      <cell>32</cell>      <cell>16</cell>      <cell>&nbsp;1</cell> <cell>&#8805;1.1.0d</cell></row>
+	<row><cell><c>des_cbc</c></cell>       <cell>&nbsp;8</cell> <cell>&nbsp;8</cell> <cell>&nbsp;8</cell> <cell></cell></row>
+	<row><cell><c>des_ede3_cbc</c></cell>  <cell>24</cell>      <cell>&nbsp;8</cell> <cell>&nbsp;8</cell> <cell></cell></row>
+	<row><cell><c>des_cfb</c></cell>       <cell>&nbsp;8</cell> <cell>&nbsp;8</cell> <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>des_ede3_cfb</c></cell>  <cell>24</cell>      <cell>&nbsp;8</cell> <cell>&nbsp;1</cell> <cell></cell></row>
+	<row><cell><c>rc2_cbc</c></cell>       <cell>16</cell>      <cell>&nbsp;8</cell> <cell>&nbsp;8</cell> <cell></cell></row>
+	<tcaption>Ciphers with IV</tcaption>
       </table>
     </section>
 
     <section>
-      <title>Stream Ciphers</title>
-      <p>To be used in <seealso marker="crypto#stream_init-2">stream_init/2</seealso> and
-      <seealso marker="crypto#stream_init/3">stream_init/3</seealso>.
+      <title>Ciphers with AEAD - cipher_aead()</title>
+      <p>To be used with:
       </p>
-      <p>To dynamically check availability, check that the name in the <i>Cipher and Mode</i> column is present in the
-      list returned by <seealso marker="crypto#supports-1">crypto:supports(ciphers)</seealso>.
+      <list>
+	<item><seealso marker="crypto#crypto_one_time_aead/6">crypto_one_time_aead/6</seealso></item>
+	<item><seealso marker="crypto#crypto_one_time_aead/7">crypto_one_time_aead/7</seealso></item>
+      </list>
+      <p>The ciphers are:
       </p>
       <table>
-	<row><cell><strong>Cipher and Mode</strong></cell><cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell><cell><strong>IV length</strong><br/><strong>[bytes]</strong></cell><cell><strong>Supported with</strong><br/><strong>OpenSSL versions</strong></cell></row>
-	<row><cell><c>aes_ctr</c></cell><cell>16, 24, 32</cell><cell>16</cell><cell>&#8805;1.0.1</cell></row>
-	<row><cell><c>rc4</c></cell><cell>&#8805;1</cell><cell> </cell> <cell>all</cell></row>
-	<tcaption>Stream cipher key lengths</tcaption>
+	<row>
+	  <cell><strong>Cipher and Mode</strong></cell>
+	  <cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell>
+	  <cell><strong>IV length</strong><br/><strong>[bytes]</strong></cell>
+	  <cell><strong>AAD length</strong><br/><strong>[bytes]</strong></cell>
+	  <cell><strong>Tag length</strong><br/><strong>[bytes]</strong></cell>
+	  <cell><strong>Block size</strong><br/><strong>[bytes]</strong></cell>
+	  <cell><strong>Limited to</strong><br/><strong>OpenSSL versions</strong></cell>
+	</row>
+	<row><cell><c>aes_128_ccm</c></cell> <cell>16</cell> <cell>7-13</cell> <cell>any</cell> <cell>even 4-16<br/>default: 12</cell> <cell>any</cell><cell>&#8805;1.0.1</cell></row>
+	<row><cell><c>aes_192_ccm</c></cell> <cell>24</cell> <cell>7-13</cell> <cell>any</cell> <cell>even 4-16<br/>default: 12</cell> <cell>any</cell><cell>&#8805;1.0.1</cell></row>
+	<row><cell><c>aes_256_ccm</c></cell> <cell>32</cell> <cell>7-13</cell> <cell>any</cell> <cell>even 4-16<br/>default: 12</cell> <cell>any</cell><cell>&#8805;1.0.1</cell></row>
+
+	<row><cell><c>aes_128_gcm</c></cell> <cell>16</cell> <cell>&#8805;1</cell> <cell>any</cell> <cell>1-16<br/>default: 16</cell> <cell>any</cell><cell>&#8805;1.0.1</cell></row>
+	<row><cell><c>aes_192_gcm</c></cell> <cell>24</cell> <cell>&#8805;1</cell> <cell>any</cell> <cell>1-16<br/>default: 16</cell> <cell>any</cell><cell>&#8805;1.0.1</cell></row>
+	<row><cell><c>aes_256_gcm</c></cell> <cell>32</cell> <cell>&#8805;1</cell> <cell>any</cell> <cell>1-16<br/>default: 16</cell> <cell>any</cell><cell>&#8805;1.0.1</cell></row>
+
+	<row><cell><c>chacha20_poly1305</c></cell><cell>32</cell> <cell>1-16</cell> <cell>any</cell> <cell>16</cell> <cell>any</cell><cell>&#8805;1.1.0</cell></row>
+	<tcaption>AEAD ciphers</tcaption>
       </table>
     </section>
   </section>
 
+  
   <section>
     <title>Message Authentication Codes (MACs)</title>
     <p>To be used in <seealso marker="crypto#mac-4">mac/4</seealso> and
@@ -129,26 +177,23 @@
       list returned by <seealso marker="crypto#supports-1">crypto:supports(ciphers)</seealso>.
       </p>
       <table>
-	<row><cell><strong>Cipher and Mode</strong></cell><cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell><cell><strong>Max Mac Length</strong><br/><strong>[bytes]</strong></cell></row>
-	<row><cell><c>aes_cbc</c></cell>  <cell>16, 24, 32</cell><cell>16</cell></row>
-	<row><cell><c>aes_cbc128</c></cell><cell>16</cell><cell>16</cell></row>
-	<row><cell><c>aes_cbc256</c></cell><cell>32</cell><cell>16</cell></row>
-
-	<row><cell><c>aes_cfb8</c></cell>  <cell>16</cell><cell>1</cell></row>
-
-	<row><cell><c>blowfish_cbc</c></cell> <cell>4-56</cell> <cell>8</cell></row>
-	<row><cell><c>blowfish_cfb64</c></cell> <cell>&#8805;1</cell> <cell>1</cell></row>
-	<row><cell><c>blowfish_ecb</c></cell><cell>&#8805;1</cell>    <cell>8</cell></row>
-	<row><cell><c>blowfish_ofb64</c></cell><cell>&#8805;1</cell>  <cell>1</cell></row>
-
-	<row><cell><c>des3_cbc</c><br/><i>(=DES EDE3 CBC)</i></cell><cell>[8,8,8]</cell><cell>8</cell></row>
-	<row><cell><c>des3_cfb</c><br/><i>(=DES EDE3 CFB)</i></cell><cell>[8,8,8]</cell><cell>1</cell></row>
-
-	<row><cell><c>des_cbc</c></cell><cell>8</cell><cell>8</cell></row>
-
-	<row><cell><c>des_cfb</c></cell><cell>8</cell><cell>1</cell></row>
-	<row><cell><c>des_ecb</c></cell><cell>8</cell><cell>1</cell></row>
-	<row><cell><c>rc2_cbc</c></cell><cell>&#8805;1</cell><cell>8</cell></row>
+	<row>
+	   <cell><strong>Cipher and Mode</strong></cell>
+	   <cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell>
+	   <cell><strong>Max Mac Length</strong><br/><strong>(= default length)</strong><br/><strong>[bytes]</strong></cell>
+	</row>
+	<row><cell><c>aes_128_cbc</c></cell>  <cell>16</cell>      <cell>16</cell></row>
+	<row><cell><c>aes_192_cbc</c></cell>  <cell>24</cell>      <cell>16</cell></row>
+	<row><cell><c>aes_256_cbc</c></cell>  <cell>32</cell>      <cell>16</cell></row>
+	<row><cell><c>aes_128_ecb</c></cell>  <cell>16</cell>      <cell>16</cell></row>
+	<row><cell><c>aes_192_ecb</c></cell>  <cell>24</cell>      <cell>16</cell></row>
+	<row><cell><c>aes_256_ecb</c></cell>  <cell>32</cell>      <cell>16</cell></row>
+	<row><cell><c>blowfish_cbc</c></cell> <cell>16</cell>      <cell>&nbsp;8</cell></row>
+	<row><cell><c>blowfish_ecb</c></cell> <cell>16</cell>      <cell>&nbsp;8</cell></row>
+	<row><cell><c>des_cbc</c></cell>      <cell>&nbsp;8</cell> <cell>&nbsp;8</cell></row>
+	<row><cell><c>des_ecb</c></cell>      <cell>&nbsp;8</cell> <cell>&nbsp;8</cell></row>
+	<row><cell><c>des_ede3_cbc</c></cell> <cell>24</cell>      <cell>&nbsp;8</cell></row>
+	<row><cell><c>rc2_cbc</c></cell>      <cell>16</cell>      <cell>&nbsp;8</cell></row>
 	<tcaption>CMAC cipher key lengths</tcaption>
       </table>
     </section>
@@ -158,8 +203,34 @@
       <p>Available in all OpenSSL compatible with Erlang CRYPTO if not disabled by configuration.
       </p>
       <p>To dynamically check availability, check that the name <c>hmac</c> is present in the
-      list returned by <seealso marker="crypto#supports-1">crypto:supports(macs)</seealso>.
+      list returned by <seealso marker="crypto#supports-1">crypto:supports(macs)</seealso> and
+      that the hash name is present in the
+      list returned by <seealso marker="crypto#supports-1">crypto:supports(hashs)</seealso>.
       </p>
+
+      <table>
+	<row>
+	   <cell><strong>Hash</strong></cell>
+	   <cell><strong>Max Mac Length</strong><br/><strong>(= default length)</strong><br/><strong>[bytes]</strong></cell>
+	</row>
+	<row><cell><c>sha</c></cell>       <cell>20</cell></row>
+	<row><cell><c>sha224</c></cell>    <cell>28</cell></row>
+	<row><cell><c>sha256</c></cell>    <cell>32</cell></row>
+	<row><cell><c>sha384</c></cell>    <cell>48</cell></row>
+	<row><cell><c>sha512</c></cell>    <cell>64</cell></row>
+	<row><cell><c>sha3_224</c></cell>  <cell>28</cell></row>
+	<row><cell><c>sha3_256</c></cell>  <cell>32</cell></row>
+	<row><cell><c>sha3_384</c></cell>  <cell>48</cell></row>
+	<row><cell><c>sha3_512</c></cell>  <cell>64</cell></row>
+	<row><cell><c>blake2b</c></cell>   <cell>64</cell></row>
+	<row><cell><c>blake2s</c></cell>   <cell>32</cell></row>
+	<row><cell><c>md4</c></cell>       <cell>16</cell></row>
+	<row><cell><c>md5</c></cell>       <cell>16</cell></row>
+	<row><cell><c>ripemd160</c></cell> <cell>20</cell></row>
+	<tcaption>HMAC output sizes</tcaption>
+      </table>
+	
+      
     </section>
 
     <section>
@@ -169,6 +240,8 @@
       <p>To dynamically check availability, check that the name <c>poly1305</c> is present in the
       list returned by <seealso marker="crypto#supports-1">crypto:supports(macs)</seealso>.
       </p>
+      <p>The poly1305 mac wants an 32 bytes key and produces a 16 byte MAC by default.
+      </p>
     </section>
 
   </section>
@@ -183,14 +256,14 @@
     <table>
       <row><cell><strong>Type</strong></cell>
            <cell><strong>Names</strong></cell>
-           <cell><strong>Supported with</strong><br/><strong>OpenSSL versions</strong></cell>
+           <cell><strong>Limitated to</strong><br/><strong>OpenSSL versions</strong></cell>
       </row>
-      <row><cell>SHA1</cell><cell>sha</cell><cell>all</cell></row>
-      <row><cell>SHA2</cell><cell>sha224, sha256, sha384, sha512</cell><cell>all</cell></row>
+      <row><cell>SHA1</cell><cell>sha</cell><cell></cell></row>
+      <row><cell>SHA2</cell><cell>sha224, sha256, sha384, sha512</cell><cell></cell></row>
       <row><cell>SHA3</cell><cell>sha3_224, sha3_256, sha3_384, sha3_512</cell><cell>&#8805;1.1.1</cell></row>
-      <row><cell>MD4</cell><cell>md4</cell><cell>all</cell></row>
-      <row><cell>MD5</cell><cell>md5</cell><cell>all</cell></row>
-      <row><cell>RIPEMD</cell><cell>ripemd160</cell><cell>all</cell></row>
+      <row><cell>MD4</cell><cell>md4</cell><cell></cell></row>
+      <row><cell>MD5</cell><cell>md5</cell><cell></cell></row>
+      <row><cell>RIPEMD</cell><cell>ripemd160</cell><cell></cell></row>
       <tcaption></tcaption>
     </table>
   </section>
diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 26fbfc166e..8988a18482 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -814,10 +814,16 @@
 	<p><c>SubType</c> depends on the MAC <c>Type</c>:
 	</p>
 	<list>
-	  <item>For <c>hmac</c> it is a hash algorithm</item>
-	  <item>For <c>cmac</c> it is a cipher suitable for cmac</item>
+	  <item>For <c>hmac</c> it is a hash algorithm, see
+	  <seealso marker="algorithm_details#hmac">Algorithm Details</seealso> in the User's Guide.
+	  </item>
+	  <item>For <c>cmac</c> it is a cipher suitable for cmac, see
+	  <seealso marker="algorithm_details#cmac">Algorithm Details</seealso> in the User's Guide.
+	  </item>
 	  <item>For <c>poly1305</c> it should be set to <c>undefined</c> or the
-	  <seealso marker="#mac-3">mac/3</seealso> function could be used instead.</item>
+	  <seealso marker="#mac_init-2">mac/2</seealso> function could be used instead, see
+	  <seealso marker="algorithm_details#poly1305">Algorithm Details</seealso> in the User's Guide.
+	  </item>
 	</list>
 
 	<p><c>Key</c> is the authentication key with a length according to the
@@ -832,6 +838,9 @@
 	<p>The <c>Mac</c> result will have a default length depending on the <c>Type</c> and <c>SubType</c>.
 	To set a shorter length, use <seealso marker="#macN-4">macN/4</seealso> or
 	<seealso marker="#macN-5">macN/5</seealso> instead.
+	The default length is documented in
+	<seealso marker="algorithm_details#message-authentication-codes--macs-">Algorithm Details</seealso>
+	in the User's Guide.
 	</p>
       </desc>
     </func>
@@ -857,6 +866,10 @@
 	bytes returned from the underlying hash, the returned hash will have
 	that shorter length instead.
 	</p>
+	<p>The max <c>MacLength</c> is documented in
+	<seealso marker="algorithm_details#message-authentication-codes--macs-">Algorithm Details</seealso>
+	in the User's Guide.
+	</p>
       </desc>
     </func>
 
@@ -881,10 +894,16 @@
 	<p><c>SubType</c> depends on the MAC <c>Type</c>:
 	</p>
 	<list>
-	  <item>For <c>hmac</c> it is a hash algorithm</item>
-	  <item>For <c>cmac</c> it is a cipher suitable for cmac</item>
+	  <item>For <c>hmac</c> it is a hash algorithm, see
+	  <seealso marker="algorithm_details#hmac">Algorithm Details</seealso> in the User's Guide.
+	  </item>
+	  <item>For <c>cmac</c> it is a cipher suitable for cmac, see
+	  <seealso marker="algorithm_details#cmac">Algorithm Details</seealso> in the User's Guide.
+	  </item>
 	  <item>For <c>poly1305</c> it should be set to <c>undefined</c> or the
-	  <seealso marker="#mac_init-2">mac/2</seealso> function could be used instead.</item>
+	  <seealso marker="#mac_init-2">mac/2</seealso> function could be used instead, see
+	  <seealso marker="algorithm_details#poly1305">Algorithm Details</seealso> in the User's Guide.
+	  </item>
 	</list>
 
 	<p><c>Key</c> is the authentication key with a length according to the
@@ -933,6 +952,9 @@
 	a default length depending on the <c>Type</c> and <c>SubType</c> in the
 	<seealso marker="#mac_init-3">mac_init/2,3</seealso> call.
 	To set a shorter length, use <seealso marker="#mac_finalN-2">mac_finalN/2</seealso> instead.
+	The default length is documented in
+	<seealso marker="algorithm_details#message-authentication-codes--macs-">Algorithm Details</seealso>
+	in the User's Guide.
 	</p>
       </desc>
     </func>
@@ -948,6 +970,10 @@
 	bytes returned from the underlying hash, the returned hash will have
 	that shorter length instead.
 	</p>
+	<p>The max <c>MacLength</c> is documented in
+	<seealso marker="algorithm_details#message-authentication-codes--macs-">Algorithm Details</seealso>
+	in the User's Guide.
+	</p>
       </desc>
     </func>
   </funcs>