crypto: A user's guide chapter on algorithm details

Such as keylengths, blocksizes and IV lengths are hard to find otherwise

Conflicts:
	lib/crypto/doc/src/crypto.xml

3 files changed, 292 insertions, 1 deletions

diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile
index 2148062e78..3203324954 100644
--- a/lib/crypto/doc/src/Makefile
+++ b/lib/crypto/doc/src/Makefile
@@ -39,7 +39,7 @@ XML_REF3_FILES = crypto.xml
 XML_REF6_FILES = crypto_app.xml
 
 XML_PART_FILES = usersguide.xml
-XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml engine_load.xml engine_keys.xml
+XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml engine_load.xml engine_keys.xml algorithm_details.xml
 
 BOOK_FILES = book.xml
 
diff --git a/lib/crypto/doc/src/algorithm_details.xml b/lib/crypto/doc/src/algorithm_details.xml
new file mode 100644
index 0000000000..088f5e8e97
--- /dev/null
+++ b/lib/crypto/doc/src/algorithm_details.xml
@@ -0,0 +1,290 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2014</year><year>2017</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+
+    </legalnotice>
+
+    <title>Algorithm Details</title>
+    <prepared>Hans Nilsson</prepared>
+    <docno></docno>
+    <date>2018-08-22</date>
+    <rev>A</rev>
+    <file>algorithm_details.xml</file>
+  </header>
+  <p>
+    This chapter describes details of algorithms in the crypto application.
+  </p>
+  <p>The tables only documents the supported cryptos and key lengths. The user should not draw any conclusion
+  on security from the supplied tables.
+  </p>
+
+  <section>
+    <title>Ciphers</title>
+    <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.
+      </p>
+      <p>To dynamically check availability, check that the name in the <i>Cipher and Mode</i> column is present in the
+      list with the <c>cipher</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </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>1-</cell> <cell>8</cell> <cell>any</cell></row>
+	<row><cell><c>blowfish_ecb</c></cell><cell>1-</cell><cell> </cell><cell>8</cell></row>
+	<row><cell><c>blowfish_ofb64</c></cell><cell>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>1-</cell><cell>8</cell><cell>8</cell></row>
+	<tcaption>Block cipher key lengths</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>.
+      </p>
+      <p>To dynamically check availability, check that the name in the <i>Cipher and Mode</i> column is present in the
+      list with the <c>cipher</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </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>Block size</strong><br/><strong>[bytes]</strong></cell><cell><strong>Supported with</strong><br/><strong>OpenSSL versions</strong></cell></row>
+	<row><cell><c>aes_gcm</c></cell> <cell>16</cell> <cell>16</cell> <cell>0-16</cell> <cell>any</cell><cell>1.0.1 -</cell></row>
+	<row><cell><c>chacha20_poly1305</c></cell><cell>32</cell> <cell>1-16</cell> <cell>any</cell> <cell>any</cell><cell>1.1.0 -</cell></row>
+	<tcaption>AEAD cipher key lengths</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>.
+      </p>
+      <p>To dynamically check availability, check that the name in the <i>Cipher and Mode</i> column is present in the
+      list with the <c>cipher</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </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>1.0.1 -</cell></row>
+	<row><cell><c>rc4</c></cell><cell>1-</cell><cell> </cell> <cell>all</cell></row>
+	<tcaption>Stream cipher key lengths</tcaption>
+      </table>
+    </section>
+  </section>
+
+  <section>
+    <title>Message Authentication Codes (MACs)</title>
+
+    <section>
+      <title>CMAC</title>
+      <p>To be used in <seealso marker="crypto#cmac-3">cmac/3</seealso> and
+      <seealso marker="crypto#cmac-3">cmac/4</seealso>.
+      </p>
+      <p>CMAC with the following ciphers are available with OpenSSL 1.0.1 or later if not disabled by configuration.
+      </p>
+
+      <p>To dynamically check availability, check that the name <c>cmac</c> is present in the
+      list with the <c>macs</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      Also check that the name in the <i>Cipher and Mode</i> column is present in the
+      list with the <c>cipher</c> tag in the return value.
+      </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>1-</cell> <cell>1</cell></row>
+	<row><cell><c>blowfish_ecb</c></cell><cell>1-</cell>    <cell>8</cell></row>
+	<row><cell><c>blowfish_ofb64</c></cell><cell>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>1-</cell><cell>8</cell></row>
+	<tcaption>CMAC cipher key lengths</tcaption>
+      </table>
+    </section>
+
+    <section>
+      <title>HMAC</title>
+      <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 with the <c>macs</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </p>
+    </section>
+
+    <section>
+      <title>POLY1305</title>
+      <p>POLY1305 is available with OpenSSL 1.1.1 or later if not disabled by configuration.
+      </p>
+      <p>To dynamically check availability, check that the name <c>poly1305</c> is present in the
+      list with the <c>macs</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </p>
+    </section>
+
+  </section>
+
+  <section>
+    <title>Hash</title>
+
+    <p>To dynamically check availability, check that the wanted name in the <i>Names</i> column is present in the
+    list with the <c>hashs</c> tag in the return value of
+    <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+    </p>
+
+
+    <table>
+      <row><cell><strong>Type</strong></cell>
+           <cell><strong>Names</strong></cell>
+           <cell><strong>Supported with</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>SHA3</cell><cell>sha3_224, sha3_256, sha3_384, sha3_512</cell><cell>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>
+      <tcaption></tcaption>
+    </table>
+  </section>
+
+  <section>
+    <title>Public Key Cryptography</title>
+
+    <section>
+      <title>RSA</title>
+      <p>RSA is available with all OpenSSL versions compatible with Erlang CRYPTO if not disabled by configuration.
+      To dynamically check availability, check that the atom <c>rsa</c> is present in the
+      list with the <c>public_keys</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </p>
+
+      <table>
+	<row><cell><strong>Option</strong></cell> <cell><strong>sign/verify</strong></cell> <cell><strong>encrypt/decrypt</strong></cell> <cell><strong>Supported with</strong><br/><strong>OpenSSL versions</strong></cell> </row>
+	<row><cell>{rsa_mgf1_md,atom()}</cell>                <cell>x</cell> <cell>x</cell>  <cell>1.0.1</cell></row>
+	<row><cell>{rsa_oaep_label, binary()}</cell>          <cell> </cell> <cell>x</cell>  <cell></cell></row>
+	<row><cell>{rsa_oaep_md, atom()}</cell>               <cell> </cell> <cell>x</cell>  <cell></cell></row>
+	<row><cell>{rsa_padding,rsa_pkcs1_pss_padding}</cell> <cell>x</cell> <cell> </cell>  <cell>1.0.0</cell></row>
+	<row><cell>{rsa_pss_saltlen, -2..}</cell>             <cell>x</cell> <cell> </cell>  <cell>1.0.0</cell></row>
+	<row><cell>{rsa_padding,rsa_no_padding}</cell>        <cell>x</cell> <cell>x</cell>  <cell></cell></row>
+	<row><cell>{rsa_padding,rsa_pkcs1_padding}</cell>     <cell>x</cell> <cell>x</cell>  <cell></cell></row>
+	<row><cell>{rsa_padding,rsa_sslv23_padding}</cell>    <cell> </cell> <cell>x</cell>  <cell></cell></row>
+	<row><cell>{rsa_padding,rsa_x931_padding}</cell>      <cell>x</cell> <cell> </cell>  <cell></cell></row>
+	<tcaption></tcaption>
+      </table>
+    </section>
+
+    <section>
+      <title>DSS</title>
+      <p>DSS is available with OpenSSL versions compatible with Erlang CRYPTO if not disabled by configuration.
+      To dynamically check availability, check that the atom <c>dss</c> is present in the
+      list with the <c>public_keys</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </p>
+    </section>
+
+    <section>
+      <title>ECDSA</title>
+      <p>ECDSA is available with OpenSSL 0.9.8o or later if not disabled by configuration.
+      To dynamically check availability, check that the atom <c>ecdsa</c> is present in the
+      list with the <c>public_keys</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      If the atom <c>ec_gf2m</c> characteristic two field curves are available.
+      </p>
+      <p>The actual supported named curves could be checked by examining the list with the
+      <c>curves</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </p>
+    </section>
+
+    <section>
+      <title>Diffie-Hellman</title>
+      <p>Diffie-Hellman computations are available with OpenSSL versions compatible with Erlang CRYPTO
+      if not disabled by configuration.
+      To dynamically check availability, check that the atom <c>dh</c> is present in the
+      list with the <c>public_keys</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </p>
+    </section>
+
+    <section>
+      <title>Elliptic Curve Diffie-Hellman</title>
+      <p>Elliptic Curve Diffie-Hellman is available with OpenSSL 0.9.8o or later if not disabled by configuration.
+      To dynamically check availability, check that the atom <c>ecdh</c> is present in the
+      list with the <c>public_keys</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </p>
+
+      <p>The Edward curves <c>x25519</c> and <c>x448</c> are supported with OpenSSL 1.1.1 or later
+      if not disabled by configuration.
+      </p>
+
+      <p>The actual supported named curves could be checked by examining the list with the
+      <c>curves</c> tag in the return value of
+      <seealso marker="crypto#supports-0">crypto:supports()</seealso>.
+      </p>
+    </section>
+
+  </section>
+
+
+</chapter>
+
+
+
+
+
diff --git a/lib/crypto/doc/src/usersguide.xml b/lib/crypto/doc/src/usersguide.xml
index 0124121433..2dfc966609 100644
--- a/lib/crypto/doc/src/usersguide.xml
+++ b/lib/crypto/doc/src/usersguide.xml
@@ -50,4 +50,5 @@
   <xi:include href="fips.xml"/>
   <xi:include href="engine_load.xml"/>
   <xi:include href="engine_keys.xml"/>
+  <xi:include href="algorithm_details.xml"/>
 </part>