diff options
Diffstat (limited to 'lib/crypto/doc/src')
| -rw-r--r-- | lib/crypto/doc/src/Makefile | 28 | ||||
| -rw-r--r-- | lib/crypto/doc/src/algorithm_details.xml | 355 | ||||
| -rw-r--r-- | lib/crypto/doc/src/crypto.xml | 1601 | ||||
| -rw-r--r-- | lib/crypto/doc/src/crypto_app.xml | 47 | ||||
| -rw-r--r-- | lib/crypto/doc/src/engine_keys.xml | 129 | ||||
| -rw-r--r-- | lib/crypto/doc/src/engine_load.xml | 129 | ||||
| -rw-r--r-- | lib/crypto/doc/src/fascicules.xml | 18 | ||||
| -rw-r--r-- | lib/crypto/doc/src/fips.xml | 211 | ||||
| -rw-r--r-- | lib/crypto/doc/src/note.gif | bin | 1539 -> 0 bytes | |||
| -rw-r--r-- | lib/crypto/doc/src/notes.xml | 574 | ||||
| -rw-r--r-- | lib/crypto/doc/src/specs.xml | 4 | ||||
| -rw-r--r-- | lib/crypto/doc/src/usersguide.xml | 11 | ||||
| -rw-r--r-- | lib/crypto/doc/src/warning.gif | bin | 1498 -> 0 bytes |
13 files changed, 2605 insertions, 502 deletions
diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile index e55242d255..cbcafb7375 100644 --- a/lib/crypto/doc/src/Makefile +++ b/lib/crypto/doc/src/Makefile @@ -9,11 +9,11 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# +# # The Initial Developer of the Original Code is Ericsson Utvecklings AB. # Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings # AB. All Rights Reserved.'' -# +# # $Id$ # include $(ERL_TOP)/make/target.mk @@ -38,13 +38,13 @@ XML_APPLICATION_FILES = ref_man.xml XML_REF3_FILES = crypto.xml XML_REF6_FILES = crypto_app.xml -XML_PART_FILES = release_notes.xml usersguide.xml -XML_CHAPTER_FILES = notes.xml licenses.xml +XML_PART_FILES = usersguide.xml +XML_CHAPTER_FILES = notes.xml licenses.xml fips.xml engine_load.xml engine_keys.xml algorithm_details.xml BOOK_FILES = book.xml XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES) $(XML_REF6_FILES) \ - $(XML_PART_FILES) $(XML_CHAPTER_FILES) + $(XML_PART_FILES) $(XML_CHAPTER_FILES) GIF_FILES = @@ -62,10 +62,16 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf +SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml) + +TOP_SPECS_FILE = specs.xml + # ---------------------------------------------------- -# FLAGS +# FLAGS # ---------------------------------------------------- -XML_FLAGS += +XML_FLAGS += + +#in ssh it looks like this: SPECS_FLAGS = -I../../../public_key/include -I../../../public_key/src -I../../.. # ---------------------------------------------------- # Targets @@ -73,7 +79,6 @@ XML_FLAGS += $(HTMLDIR)/%.gif: %.gif $(INSTALL_DATA) $< $@ - docs: pdf html man $(TOP_PDF_FILE): $(XML_FILES) @@ -86,18 +91,20 @@ man: $(MAN3_FILES) $(MAN6_FILES) gifs: $(GIF_FILES:%=$(HTMLDIR)/%) -debug opt valgrind: +debug opt valgrind: clean clean_docs clean_tex: rm -rf $(HTMLDIR)/* + rm -rf $(XMLDIR) rm -f $(MAN3DIR)/* rm -f $(MAN6DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f $(SPECS_FILES) rm -f errs core *~ # ---------------------------------------------------- # Release Target -# ---------------------------------------------------- +# ---------------------------------------------------- include $(ERL_TOP)/make/otp_release_targets.mk release_docs_spec: docs @@ -114,4 +121,3 @@ release_docs_spec: docs release_spec: - diff --git a/lib/crypto/doc/src/algorithm_details.xml b/lib/crypto/doc/src/algorithm_details.xml new file mode 100644 index 0000000000..854bfbb4b1 --- /dev/null +++ b/lib/crypto/doc/src/algorithm_details.xml @@ -0,0 +1,355 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2014</year><year>2018</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>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>≥1.1.0</cell></row> + <row><cell><c>aes_gcm</c></cell> <cell>16,24,32</cell> <cell>≥1</cell> <cell>any</cell> <cell>1-16<br/>default: 16</cell> <cell>any</cell><cell>≥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>≥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> + <warning> + <!-- In RefMan rsa_opt(), rsa_sign_verify_opt() and User's man RSA --> + <p>The RSA options are experimental. + </p> + <p>The exact set of options and there syntax <em>may</em> be changed + without prior notice.</p> + </warning> + <table> + <row><cell><strong>Option</strong></cell> + <cell><strong>sign/verify</strong></cell> + <cell><strong>public encrypt</strong><br/><strong>private decrypt</strong></cell> + <cell><strong>private encrypt</strong><br/><strong>public decrypt</strong></cell> + </row> + <row><cell>{rsa_padding,rsa_x931_padding}</cell> + <cell>x</cell> + <cell></cell> + <cell>x</cell> + </row> + <row><cell>{rsa_padding,rsa_pkcs1_padding}</cell> + <cell>x</cell> + <cell>x</cell> + <cell>x</cell> + </row> + <row><cell>{rsa_padding,rsa_pkcs1_pss_padding}<br/> + {rsa_pss_saltlen, -2..}<br/> + {rsa_mgf1_md, atom()} + </cell> + <cell>x (2)<br/> + x (2)<br/> + x (2)</cell> + <cell></cell> + <cell></cell> + </row> + <row><cell>{rsa_padding,rsa_pkcs1_oaep_padding}<br/> + {rsa_mgf1_md, atom()}<br/> + {rsa_oaep_label, binary()}}<br/> + {rsa_oaep_md, atom()} + </cell> + <cell></cell> + <cell>x (2)<br/> + x (2)<br/> + x (3)<br/> + x (3) + </cell> + <cell></cell> + </row> + <row><cell>{rsa_padding,rsa_no_padding}</cell> + <cell>x (1)</cell> + <cell></cell> + <cell></cell> + </row> + <!-- row><cell>{rsa_padding,rsa_sslv23_padding}</cell> + <cell></cell> + <cell></cell> + <cell></cell> + </row --> + <tcaption></tcaption> + </table> + <p>Notes:</p> + <list type="ordered"> + <item>(1) OpenSSL ≤ 1.0.0</item> + <item>(2) OpenSSL ≥ 1.0.1</item> + <item>(3) OpenSSL ≥ 1.1.0</item> + </list> + </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>EdDSA</title> + <p>EdDSA is available with OpenSSL 1.1.1 or later if not disabled by configuration. + To dynamically check availability, check that the atom <c>eddsa</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>Support for the curves ed25519 and ed448 is implemented. + 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/crypto.xml b/lib/crypto/doc/src/crypto.xml index 82e450ec21..5c1909fc7f 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -4,14 +4,14 @@ <erlref> <header> <copyright> - <year>1999</year><year>2017</year> + <year>1999</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,197 +19,546 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - </legalnotice> <title>crypto</title> </header> - <module>crypto</module> + <module since="">crypto</module> <modulesummary>Crypto Functions</modulesummary> <description> <p>This module provides a set of cryptographic functions. </p> - <list type="bulleted"> - <item> - <p>Hash functions - - <url href="http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf"> Secure Hash Standard</url>, - <url href="http://www.ietf.org/rfc/rfc1321.txt"> The MD5 Message Digest Algorithm (RFC 1321)</url> and - <url href="http://www.ietf.org/rfc/rfc1320.txt">The MD4 Message Digest Algorithm (RFC 1320)</url> - </p> - </item> - <item> - <p>Hmac functions - <url href="http://www.ietf.org/rfc/rfc2104.txt"> Keyed-Hashing for Message Authentication (RFC 2104) </url></p> - </item> - <item> - <p>Block ciphers - <url href="http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html"> </url> DES and AES in - Block Cipher Modes - <url href="http://csrc.nist.gov/groups/ST/toolkit/BCM/index.html"> ECB, CBC, CFB, OFB, CTR and GCM </url></p> - </item> - <item> - <p><url href="http://www.ietf.org/rfc/rfc1321.txt"> RSA encryption RFC 1321 </url> </p> - </item> - <item> - <p>Digital signatures <url href="http://csrc.nist.gov/publications/drafts/fips186-3/fips_186-3.pdf">Digital Signature Standard (DSS)</url> and<url href="http://csrc.nist.gov/groups/STM/cavp/documents/dss2/ecdsa2vs.pdf"> Elliptic Curve Digital - Signature Algorithm (ECDSA) </url> </p> - </item> - <item> - <p><url href="http://www.ietf.org/rfc/rfc2945.txt"> Secure Remote Password Protocol (SRP - RFC 2945) </url></p> - </item> - <item> - <p>gcm: Dworkin, M., "Recommendation for Block Cipher Modes of - Operation: Galois/Counter Mode (GCM) and GMAC", - National Institute of Standards and Technology SP 800- - 38D, November 2007.</p> - </item> - </list> + <taglist> + <tag>Hash functions</tag> + <item> + <p></p> + <taglist> + <tag>SHA1, SHA2</tag> + <item> + <url href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf"> + Secure Hash Standard [FIPS PUB 180-4] + </url> + </item> + <tag>SHA3</tag> + <item> + <url href="https://www.nist.gov/publications/sha-3-standard-permutation-based-hash-and-extendable-output-functions?pub_id=919061"> + SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions [FIPS PUB 202] + </url> + </item> + <tag>MD5</tag> + <item> + <url href="http://www.ietf.org/rfc/rfc1321.txt">The MD5 Message Digest Algorithm [RFC 1321]</url> + </item> + <tag>MD4</tag> + <item> + <url href="http://www.ietf.org/rfc/rfc1320.txt">The MD4 Message Digest Algorithm [RFC 1320]</url> + </item> + </taglist> + <p></p> + </item> + + <tag>MACs - Message Authentication Codes</tag> + <item> + <p></p> + <taglist> + <tag>Hmac functions</tag> + <item> + <url href="http://www.ietf.org/rfc/rfc2104.txt"> + Keyed-Hashing for Message Authentication [RFC 2104] + </url> + </item> + <tag>Cmac functions</tag> + <item> + <url href="http://www.ietf.org/rfc/rfc4493.txt"> + The AES-CMAC Algorithm [RFC 4493] + </url> + </item> + <tag>POLY1305</tag> + <item> + <url href="http://www.ietf.org/rfc/rfc7539.txt"> + ChaCha20 and Poly1305 for IETF Protocols [RFC 7539] + </url> + </item> + </taglist> + <p></p> + </item> + + <tag>Symmetric Ciphers</tag> + <item> + <p></p> + <taglist> + <tag>DES, 3DES and AES</tag> + <item> + <url href="https://csrc.nist.gov/projects/block-cipher-techniques">Block Cipher Techniques [NIST]</url> + </item> + <tag>Blowfish</tag> + <item> + <url href="https://www.schneier.com/academic/archives/1994/09/description_of_a_new.html"> + Fast Software Encryption, Cambridge Security Workshop Proceedings (December 1993), Springer-Verlag, 1994, pp. 191-204. + </url> + </item> + <tag>Chacha20</tag> + <item> + <url href="http://www.ietf.org/rfc/rfc7539.txt"> + ChaCha20 and Poly1305 for IETF Protocols [RFC 7539] + </url> + </item> + <tag>Chacha20_poly1305</tag> + <item> + <url href="http://www.ietf.org/rfc/rfc7539.txt"> + ChaCha20 and Poly1305 for IETF Protocols [RFC 7539] + </url> + </item> + </taglist> + <p></p> + </item> + + <tag>Modes</tag> + <item> + <p></p> + <taglist> + <tag>ECB, CBC, CFB, OFB and CTR</tag> + <item> + <url href="https://csrc.nist.gov/publications/detail/sp/800-38a/final"> + Recommendation for Block Cipher Modes of Operation: Methods and Techniques [NIST SP 800-38A] + </url> + </item> + <tag>GCM</tag> + <item> + <url href="https://csrc.nist.gov/publications/detail/sp/800-38d/final"> + Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC [NIST SP 800-38D] + </url> + </item> + <tag>CCM</tag> + <item> + <url href="https://nvlpubs.nist.gov/nistpubs/legacy/sp/nistspecialpublication800-38c.pdf"> + Recommendation for Block Cipher Modes of Operation: + The CCM Mode for Authentication and Confidentiality [NIST SP 800-38C] + </url> + </item> + </taglist> + <p></p> + </item> + + <tag>Asymetric Ciphers - Public Key Techniques</tag> + <item> + <p></p> + <taglist> + <tag>RSA</tag> + <item> + <url href="http://www.ietf.org/rfc/rfc3447.txt"> + PKCS #1: RSA Cryptography Specifications [RFC 3447] + </url> + </item> + <tag>DSS</tag> + <item> + <url href="https://csrc.nist.gov/publications/detail/fips/186/4/final"> + Digital Signature Standard (DSS) [FIPS 186-4] + </url> + </item> + <tag>ECDSA</tag> + <item> + <url href="http://csrc.nist.gov/groups/STM/cavp/documents/dss2/ecdsa2vs.pdf"> + Elliptic Curve Digital Signature Algorithm [ECDSA] + </url> + </item> + <tag>SRP</tag> + <item> + <url href="http://www.ietf.org/rfc/rfc2945.txt"> + The SRP Authentication and Key Exchange System [RFC 2945] + </url> + </item> + </taglist> + <p></p> + </item> + </taglist> + + <note> + <p>The actual supported algorithms and features depends on their availability in the actual libcrypto used. + See the <seealso marker="crypto:crypto_app">crypto (App)</seealso> about dependencies. + </p> + <p>Enabling FIPS mode will also disable algorithms and features. + </p> + </note> + + <p>The <seealso marker="users_guide">CRYPTO User's Guide</seealso> has more information on + FIPS, Engines and Algorithm Details like key lengths. + </p> </description> - <section> - <title>DATA TYPES </title> - - <code>key_value() = integer() | binary() </code> - <p>Always <c>binary()</c> when used as return value</p> + <datatypes> + <datatype_title>Ciphers</datatype_title> + <datatype> + <name name="stream_cipher"/> + <desc> + <p>Stream ciphers for + <seealso marker="#stream_encrypt-2">stream_encrypt/2</seealso> and + <seealso marker="#stream_decrypt-2">stream_decrypt/2</seealso> . + </p> + </desc> + </datatype> - <code>rsa_public() = [key_value()] = [E, N] </code> - <p> Where E is the public exponent and N is public modulus. </p> + <datatype> + <name name="block_cipher_with_iv"/> + <name name="cbc_cipher"/> + <name name="cfb_cipher"/> + <desc> + <p>Block ciphers with initialization vector for + <seealso marker="#block_encrypt-4">block_encrypt/4</seealso> and + <seealso marker="#block_decrypt-4">block_decrypt/4</seealso> . + </p> + </desc> + </datatype> - <code>rsa_private() = [key_value()] = [E, N, D] | [E, N, D, P1, P2, E1, E2, C] </code> - <p>Where E is the public exponent, N is public modulus and D is - the private exponent.The longer key format contains redundant - information that will make the calculation faster. P1,P2 are first - and second prime factors. E1,E2 are first and second exponents. C - is the CRT coefficient. Terminology is taken from <url href="http://www.ietf.org/rfc/rfc3477.txt"> RFC 3447</url>.</p> + <datatype> + <name name="block_cipher_without_iv"/> + <name name="ecb_cipher"/> + <desc> + <p>Block ciphers without initialization vector for + <seealso marker="#block_encrypt-3">block_encrypt/3</seealso> and + <seealso marker="#block_decrypt-3">block_decrypt/3</seealso> . + </p> + </desc> + </datatype> - <code>dss_public() = [key_value()] = [P, Q, G, Y] </code> - <p>Where P, Q and G are the dss parameters and Y is the public key.</p> + <datatype> + <name name="aead_cipher"/> + <desc> + <p>Ciphers with simultaneous MAC-calculation or MAC-checking. + <seealso marker="#block_encrypt-4">block_encrypt/4</seealso> and + <seealso marker="#block_decrypt-4">block_decrypt/4</seealso> . + </p> + </desc> + </datatype> - <code>dss_private() = [key_value()] = [P, Q, G, X] </code> - <p>Where P, Q and G are the dss parameters and X is the private key.</p> + <datatype_title>Digests</datatype_title> + <datatype> + <name name="sha1"/> + <name name="sha2"/> + <name name="sha3"/> + <desc> + </desc> + </datatype> - <code>srp_public() = key_value() </code> - <p>Where is <c>A</c> or <c>B</c> from <url href="http://srp.stanford.edu/design.html">SRP design</url></p> + <datatype> + <name name="compatibility_only_hash"/> + <desc> + <p>The <c>compatibility_only_hash()</c> algorithms are recommended only for compatibility with existing applications.</p> + </desc> + </datatype> - <code>srp_private() = key_value() </code> - <p>Where is <c>a</c> or <c>b</c> from <url href="http://srp.stanford.edu/design.html">SRP design</url></p> + <datatype> + <name name="rsa_digest_type"/> + <desc> + </desc> + </datatype> - <p>Where Verifier is <c>v</c>, Generator is <c>g</c> and Prime is<c> N</c>, DerivedKey is <c>X</c>, and Scrambler is - <c>u</c> (optional will be generated if not provided) from <url href="http://srp.stanford.edu/design.html">SRP design</url> - Version = '3' | '6' | '6a' - </p> + <datatype> + <name name="dss_digest_type"/> + <desc> + </desc> + </datatype> - <code>dh_public() = key_value() </code> + <datatype> + <name name="ecdsa_digest_type"/> + <desc> + </desc> + </datatype> - <code>dh_private() = key_value() </code> + <datatype_title>Elliptic Curves</datatype_title> + <datatype> + <name name="ec_named_curve"/> + <name name="edwards_curve_dh"/> + <name name="edwards_curve_ed"/> + <desc> + <p>Note that some curves are disabled if FIPS is enabled.</p> + </desc> + </datatype> - <code>dh_params() = [key_value()] = [P, G] | [P, G, PrivateKeyBitLength]</code> + <datatype> + <name name="ec_explicit_curve"/> + <name name="ec_field"/> + <name name="ec_curve"/> + <desc> + <p>Parametric curve definition.</p> + </desc> + </datatype> - <code>ecdh_public() = key_value() </code> + <datatype> + <name name="ec_prime_field"/> + <name name="ec_characteristic_two_field"/> + <name name="ec_basis"/> + <desc> + <p>Curve definition details.</p> + </desc> + </datatype> - <code>ecdh_private() = key_value() </code> + <datatype_title>Keys</datatype_title> + <datatype> + <name name="key"/> + <name name="des3_key"/> + <desc> + <p>For keylengths, iv-sizes and blocksizes see the + <seealso marker="crypto:algorithm_details#ciphers">User's Guide</seealso>. + </p> + <p>A key for des3 is a list of three iolists</p> + </desc> + </datatype> - <code>ecdh_params() = ec_named_curve() | ec_explicit_curve()</code> + <datatype> + <name name="key_integer"/> + <desc> + <p>Always <c>binary()</c> when used as return value</p> + </desc> + </datatype> - <code>ec_explicit_curve() = - {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(), CoFactor :: none | integer()} </code> + <datatype_title>Public/Private Keys</datatype_title> + <datatype> + <name name="rsa_public"/> + <name name="rsa_private"/> + <name name="rsa_params"/> + <desc> + <code>rsa_public() = [E, N]</code> + <code>rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]</code> + <p>Where E is the public exponent, N is public modulus and D is + the private exponent. The longer key format contains redundant + information that will make the calculation faster. P1,P2 are first + and second prime factors. E1,E2 are first and second exponents. C + is the CRT coefficient. Terminology is taken from <url href="http://www.ietf.org/rfc/rfc3477.txt"> RFC 3447</url>.</p> + </desc> + </datatype> - <code>ec_field() = {prime_field, Prime :: integer()} | - {characteristic_two_field, M :: integer(), Basis :: ec_basis()}</code> + <datatype> + <name name="dss_public"/> + <name name="dss_private"/> + <desc> + <code>dss_public() = [P, Q, G, Y] </code> + <p>Where P, Q and G are the dss parameters and Y is the public key.</p> - <code>ec_basis() = {tpbasis, K :: non_neg_integer()} | - {ppbasis, K1 :: non_neg_integer(), K2 :: non_neg_integer(), K3 :: non_neg_integer()} | - onbasis</code> + <code>dss_private() = [P, Q, G, X] </code> + <p>Where P, Q and G are the dss parameters and X is the private key.</p> + </desc> + </datatype> - <code>ec_named_curve() -> - sect571r1| sect571k1| sect409r1| sect409k1| secp521r1| secp384r1| secp224r1| secp224k1| - secp192k1| secp160r2| secp128r2| secp128r1| sect233r1| sect233k1| sect193r2| sect193r1| - sect131r2| sect131r1| sect283r1| sect283k1| sect163r2| secp256k1| secp160k1| secp160r1| - secp112r2| secp112r1| sect113r2| sect113r1| sect239k1| sect163r1| sect163k1| secp256r1| - secp192r1| - brainpoolP160r1| brainpoolP160t1| brainpoolP192r1| brainpoolP192t1| brainpoolP224r1| - brainpoolP224t1| brainpoolP256r1| brainpoolP256t1| brainpoolP320r1| brainpoolP320t1| - brainpoolP384r1| brainpoolP384t1| brainpoolP512r1| brainpoolP512t1 - </code> - <p>Note that the <em>sect</em> curves are GF2m (characteristic two) curves and are only supported if the - underlying OpenSSL has support for them. - See also <seealso marker="#supports-0">crypto:supports/0</seealso> - </p> + <datatype> + <name name="ecdsa_public"/> + <name name="ecdsa_private"/> + <name name="ecdsa_params"/> + <desc> + </desc> + </datatype> - <code>stream_cipher() = rc4 | aes_ctr </code> + <datatype> + <name name="eddsa_public"/> + <name name="eddsa_private"/> + <name name="eddsa_params"/> + <desc> + </desc> + </datatype> - <code>block_cipher() = aes_cbc | aes_cfb8 | aes_cfb128 | aes_ige256 | blowfish_cbc | - blowfish_cfb64 | des_cbc | des_cfb | des3_cbc | des3_cfb | des_ede3 | rc2_cbc </code> + <datatype> + <name name="srp_public"/> + <name name="srp_private"/> + <desc> + <code>srp_public() = key_integer() </code> + <p>Where is <c>A</c> or <c>B</c> from <url href="http://srp.stanford.edu/design.html">SRP design</url></p> + + <code>srp_private() = key_integer() </code> + <p>Where is <c>a</c> or <c>b</c> from <url href="http://srp.stanford.edu/design.html">SRP design</url></p> + </desc> + </datatype> - <code>aead_cipher() = aes_gcm | chacha20_poly1305 </code> + <datatype> + <name name="srp_gen_params"/> + <name name="srp_comp_params"/> + <desc> + <marker id="type-srp_user_gen_params"/> + <code>srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]</code> + <marker id="type-srp_host_gen_params"/> + <code>srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]</code> + <marker id="type-srp_user_comp_params"/> + <code>srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]</code> + <marker id="type-srp_host_comp_params"/> + <code>srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]</code> + <p>Where Verifier is <c>v</c>, Generator is <c>g</c> and Prime is<c> N</c>, DerivedKey is <c>X</c>, and Scrambler is + <c>u</c> (optional will be generated if not provided) from <url href="http://srp.stanford.edu/design.html">SRP design</url> + Version = '3' | '6' | '6a' + </p> + </desc> + </datatype> - <code>stream_key() = aes_key() | rc4_key() </code> + <datatype_title>Public Key Ciphers</datatype_title> - <code>block_key() = aes_key() | blowfish_key() | des_key()| des3_key() </code> + <datatype> + <name name="pk_encrypt_decrypt_algs"/> + <desc> + <p>Algorithms for public key encrypt/decrypt. Only RSA is supported.</p> + </desc> + </datatype> - <code>aes_key() = iodata() </code> <p>Key length is 128, 192 or 256 bits</p> + <datatype> + <name name="pk_encrypt_decrypt_opts"/> + <name name="rsa_opt"/> + <name name="rsa_padding"/> + <desc> + <p>Options for public key encrypt/decrypt. Only RSA is supported.</p> + <warning> + <!-- In RefMan rsa_opt(), rsa_sign_verify_opt() and User's man RSA --> + <p>The RSA options are experimental. + </p> + <p>The exact set of options and there syntax <em>may</em> be changed + without prior notice.</p> + </warning> + </desc> + </datatype> - <code>rc4_key() = iodata() </code> <p>Variable key length from 8 bits up to 2048 bits (usually between 40 and 256)</p> + <datatype> + <name name="rsa_compat_opts"/> + <desc> + <p>Those option forms are kept only for compatibility and should not be used in new code.</p> + </desc> + </datatype> - <code>blowfish_key() = iodata() </code> <p>Variable key length from 32 bits up to 448 bits</p> + <datatype_title>Public Key Sign and Verify</datatype_title> - <code>des_key() = iodata() </code> <p>Key length is 64 bits (in CBC mode only 8 bits are used)</p> + <datatype> + <name name="pk_sign_verify_algs"/> + <desc> + <p>Algorithms for sign and verify.</p> + </desc> + </datatype> - <code>des3_key() = [binary(), binary(), binary()] </code> <p>Each key part is 64 bits (in CBC mode only 8 bits are used)</p> + <datatype> + <name name="pk_sign_verify_opts"/> + <name name="rsa_sign_verify_opt"/> + <name name="rsa_sign_verify_padding"/> + <desc> + <p>Options for sign and verify.</p> + <warning> + <!-- In RefMan rsa_opt(), rsa_sign_verify_opt() and User's man RSA --> + <p>The RSA options are experimental. + </p> + <p>The exact set of options and there syntax <em>may</em> be changed + without prior notice.</p> + </warning> + </desc> + </datatype> + + <datatype_title>Diffie-Hellman Keys and parameters</datatype_title> + <datatype> + <name name="dh_public"/> + <name name="dh_private"/> + <desc> + </desc> + </datatype> - <code>digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512</code> + <datatype> + <name name="dh_params"/> + <desc> + <code>dh_params() = [P, G] | [P, G, PrivateKeyBitLength]</code> + </desc> + </datatype> - <code> hash_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 </code> <p>md4 is also supported for hash_init/1 and hash/2. - Note that both md4 and md5 are recommended only for compatibility with existing applications. - </p> - <code> cipher_algorithms() = aes_cbc | aes_cfb8 | aes_cfb128 | aes_ctr | aes_gcm | - aes_ige256 | blowfish_cbc | blowfish_cfb64 | chacha20_poly1305 | des_cbc | des_cfb | - des3_cbc | des3_cfb | des_ede3 | rc2_cbc | rc4 </code> - <code> public_key_algorithms() = rsa |dss | ecdsa | dh | ecdh | ec_gf2m</code> - <p>Note that ec_gf2m is not strictly a public key algorithm, but a restriction on what curves are supported - with ecdsa and ecdh. - </p> + <datatype> + <name name="ecdh_public"/> + <name name="ecdh_private"/> + <name name="ecdh_params"/> + <desc> + </desc> + </datatype> - </section> + <datatype_title>Types for Engines</datatype_title> + <datatype> + <name name="engine_key_ref"/> + <name name="engine_ref"/> + <desc> + <p>The result of a call to <seealso marker="#engine_load-3">engine_load/3</seealso>. + </p> + </desc> + </datatype> + + <datatype> + <name name="key_id"/> + <desc> + <p>Identifies the key to be used. The format depends on the loaded engine. It is passed to + the <c>ENGINE_load_(private|public)_key</c> functions in libcrypto. + </p> + </desc> + </datatype> + + <datatype> + <name name="password"/> + <desc> + <p>The password of the key stored in an engine. + </p> + </desc> + </datatype> + + <datatype> + <name name="engine_method_type"/> + </datatype> + + <datatype> + <name name="engine_cmnd"/> + <desc> + <p>Pre and Post commands for <seealso marker="#engine_load-3">engine_load/3 and /4</seealso>. + </p> + </desc> + </datatype> + + <datatype_title>Internal data types</datatype_title> + + <datatype> + <name name="stream_state"/> + <name name="hmac_state"/> + <name name="hash_state"/> + <desc> + <p>Contexts with an internal state that should not be manipulated but passed between function calls. + </p> + </desc> + </datatype> + + </datatypes> + + <!--================ FUNCTIONS ================--> <funcs> <func> - <name>block_encrypt(Type, Key, PlainText) -> CipherText</name> + <name name="block_encrypt" arity="3" since="OTP 18.0"/> <fsummary>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher</fsummary> - <type> - <v>Type = des_ecb | blowfish_ecb | aes_ecb </v> - <v>Key = block_key() </v> - <v>PlainText = iodata() </v> - </type> <desc> - <p>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher.</p> - <p>May throw exception <c>notsup</c> in case the chosen <c>Type</c> - is not supported by the underlying OpenSSL implementation.</p> + <p>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher.</p> + <p>May raise exception <c>error:notsup</c> in case the chosen <c>Type</c> + is not supported by the underlying libcrypto implementation.</p> + <p>For keylengths and blocksizes see the + <seealso marker="crypto:algorithm_details#ciphers">User's Guide</seealso>. + </p> </desc> </func> <func> - <name>block_decrypt(Type, Key, CipherText) -> PlainText</name> + <name name="block_decrypt" arity="3" since="OTP 18.0"/> <fsummary>Decrypt <c>CipherText</c> according to <c>Type</c> block cipher</fsummary> - <type> - <v>Type = des_ecb | blowfish_ecb | aes_ecb </v> - <v>Key = block_key() </v> - <v>PlainText = iodata() </v> - </type> <desc> <p>Decrypt <c>CipherText</c> according to <c>Type</c> block cipher.</p> - <p>May throw exception <c>notsup</c> in case the chosen <c>Type</c> - is not supported by the underlying OpenSSL implementation.</p> + <p>May raise exception <c>error:notsup</c> in case the chosen <c>Type</c> + is not supported by the underlying libcrypto implementation.</p> + <p>For keylengths and blocksizes see the + <seealso marker="crypto:algorithm_details#ciphers">User's Guide</seealso>. + </p> </desc> </func> <func> - <name>block_encrypt(Type, Key, Ivec, PlainText) -> CipherText</name> - <name>block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText, CipherTag}</name> - <name>block_encrypt(aes_gcm, Key, Ivec, {AAD, PlainText, TagLength}) -> {CipherText, CipherTag}</name> + <name since="OTP R16B01">block_encrypt(Type, Key, Ivec, PlainText) -> CipherText</name> + <name since="OTP R16B01">block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText, CipherTag}</name> + <name since="OTP R16B01">block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText, TagLength}) -> {CipherText, CipherTag}</name> <fsummary>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher</fsummary> <type> - <v>Type = block_cipher() </v> - <v>AeadType = aead_cipher() </v> - <v>Key = block_key() </v> - <v>PlainText = iodata() </v> + <v>Type = <seealso marker="#type-block_cipher_with_iv">block_cipher_with_iv()</seealso></v> + <v>AeadType = <seealso marker="#type-aead_cipher">aead_cipher()</seealso></v> + <v>Key = <seealso marker="#type-key">key()</seealso> | <seealso marker="#type-des3_key">des3_key()</seealso></v> + <v>PlainText = iodata()</v> <v>AAD = IVec = CipherText = CipherTag = binary()</v> <v>TagLength = 1..16</v> </type> @@ -219,20 +568,23 @@ <p>In AEAD (Authenticated Encryption with Associated Data) mode, encrypt <c>PlainText</c>according to <c>Type</c> block cipher and calculate <c>CipherTag</c> that also authenticates the <c>AAD</c> (Associated Authenticated Data).</p> - <p>May throw exception <c>notsup</c> in case the chosen <c>Type</c> - is not supported by the underlying OpenSSL implementation.</p> + <p>May raise exception <c>error:notsup</c> in case the chosen <c>Type</c> + is not supported by the underlying libcrypto implementation.</p> + <p>For keylengths, iv-sizes and blocksizes see the + <seealso marker="crypto:algorithm_details#ciphers">User's Guide</seealso>. + </p> </desc> </func> <func> - <name>block_decrypt(Type, Key, Ivec, CipherText) -> PlainText</name> - <name>block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) -> PlainText | error</name> + <name since="OTP R16B01">block_decrypt(Type, Key, Ivec, CipherText) -> PlainText</name> + <name since="OTP R16B01">block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) -> PlainText | error</name> <fsummary>Decrypt <c>CipherText</c> according to <c>Type</c> block cipher</fsummary> <type> - <v>Type = block_cipher() </v> - <v>AeadType = aead_cipher() </v> - <v>Key = block_key() </v> - <v>PlainText = iodata() </v> + <v>Type = <seealso marker="#type-block_cipher_with_iv">block_cipher_with_iv()</seealso></v> + <v>AeadType = <seealso marker="#type-aead_cipher">aead_cipher()</seealso></v> + <v>Key = <seealso marker="#type-key">key()</seealso> | <seealso marker="#type-des3_key">des3_key()</seealso></v> + <v>PlainText = iodata()</v> <v>AAD = IVec = CipherText = CipherTag = binary()</v> </type> <desc> @@ -242,19 +594,17 @@ <c>CipherText</c>according to <c>Type</c> block cipher and check the authenticity the <c>PlainText</c> and <c>AAD</c> (Associated Authenticated Data) using the <c>CipherTag</c>. May return <c>error</c> if the decryption or validation fail's</p> - <p>May throw exception <c>notsup</c> in case the chosen <c>Type</c> - is not supported by the underlying OpenSSL implementation.</p> + <p>May raise exception <c>error:notsup</c> in case the chosen <c>Type</c> + is not supported by the underlying libcrypto implementation.</p> + <p>For keylengths, iv-sizes and blocksizes see the + <seealso marker="crypto:algorithm_details#ciphers">User's Guide</seealso>. + </p> </desc> </func> - + <func> - <name>bytes_to_integer(Bin) -> Integer </name> + <name name="bytes_to_integer" arity="1" since="OTP R16B01"/> <fsummary>Convert binary representation, of an integer, to an Erlang integer.</fsummary> - <type> - <v>Bin = binary() - as returned by crypto functions</v> - - <v>Integer = integer() </v> - </type> <desc> <p>Convert binary representation, of an integer, to an Erlang integer. </p> @@ -262,17 +612,8 @@ </func> <func> - <name>compute_key(Type, OthersPublicKey, MyKey, Params) -> SharedSecret</name> + <name name="compute_key" arity="4" since="OTP R16B01"/> <fsummary>Computes the shared secret</fsummary> - <type> - <v> Type = dh | ecdh | srp </v> - <v>OthersPublicKey = dh_public() | ecdh_public() | srp_public() </v> - <v>MyKey = dh_private() | ecdh_private() | {srp_public(),srp_private()}</v> - <v>Params = dh_params() | ecdh_params() | SrpUserParams | SrpHostParams</v> - <v>SrpUserParams = {user, [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | [Scrambler:binary()]]} </v> - <v>SrpHostParams = {host, [Verifier::binary(), Prime::binary(), Version::atom() | [Scrambler::binary]]} </v> - <v>SharedSecret = binary()</v> - </type> <desc> <p>Computes the shared secret from the private key and the other party's public key. See also <seealso marker="public_key:public_key#compute_key-2">public_key:compute_key/2</seealso> @@ -281,75 +622,61 @@ </func> <func> - <name>exor(Data1, Data2) -> Result</name> + <name name="exor" arity="2" since=""/> <fsummary>XOR data</fsummary> - <type> - <v>Data1, Data2 = iodata()</v> - <v>Result = binary()</v> - </type> <desc> <p>Performs bit-wise XOR (exclusive or) on the data supplied.</p> </desc> </func> - <func> - <name>generate_key(Type, Params) -> {PublicKey, PrivKeyOut} </name> - <name>generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut} </name> - <fsummary>Generates a public keys of type <c>Type</c></fsummary> - <type> - <v> Type = dh | ecdh | srp </v> - <v>Params = dh_params() | ecdh_params() | SrpUserParams | SrpHostParams </v> - <v>SrpUserParams = {user, [Generator::binary(), Prime::binary(), Version::atom()]}</v> - <v>SrpHostParams = {host, [Verifier::binary(), Generator::binary(), Prime::binary(), Version::atom()]}</v> - <v>PublicKey = dh_public() | ecdh_public() | srp_public() </v> - <v>PrivKeyIn = undefined | dh_private() | ecdh_private() | srp_private() </v> - <v>PrivKeyOut = dh_private() | ecdh_private() | srp_private() </v> - </type> + + <func> + <name name="generate_key" arity="2" since="OTP R16B01"/> + <name name="generate_key" arity="3" since="OTP R16B01"/> + <fsummary>Generates a public key of type <c>Type</c></fsummary> <desc> - <p>Generates public keys of type <c>Type</c>. - See also <seealso marker="public_key:public_key#generate_key-1">public_key:generate_key/1</seealso> - May throw exception <c>low_entropy</c> in case the random generator - failed due to lack of secure "randomness". - </p> + <p>Generates a public key of type <c>Type</c>. + See also <seealso marker="public_key:public_key#generate_key-1">public_key:generate_key/1</seealso>. + May raise exception: + </p> + <list type="bulleted"> + <item><c>error:badarg</c>: an argument is of wrong type or has an illegal value,</item> + <item><c>error:low_entropy</c>: the random generator failed due to lack of secure "randomness",</item> + <item><c>error:computation_failed</c>: the computation fails of another reason than <c>low_entropy</c>.</item> + </list> + <note> + <p>RSA key generation is only available if the runtime was + built with dirty scheduler support. Otherwise, attempting to + generate an RSA key will raise exception <c>error:notsup</c>.</p> + </note> </desc> </func> <func> - <name>hash(Type, Data) -> Digest</name> + <name name="hash" arity="2" since="OTP R15B02"/> <fsummary></fsummary> - <type> - <v>Type = md4 | hash_algorithms()</v> - <v>Data = iodata()</v> - <v>Digest = binary()</v> - </type> <desc> <p>Computes a message digest of type <c>Type</c> from <c>Data</c>.</p> - <p>May throw exception <c>notsup</c> in case the chosen <c>Type</c> - is not supported by the underlying OpenSSL implementation.</p> + <p>May raise exception <c>error:notsup</c> in case the chosen <c>Type</c> + is not supported by the underlying libcrypto implementation.</p> </desc> </func> <func> - <name>hash_init(Type) -> Context</name> + <name name="hash_init" arity="1" since="OTP R15B02"/> <fsummary></fsummary> - <type> - <v>Type = md4 | hash_algorithms()</v> - </type> <desc> <p>Initializes the context for streaming hash operations. <c>Type</c> determines which digest to use. The returned context should be used as argument to <seealso marker="#hash_update-2">hash_update</seealso>.</p> - <p>May throw exception <c>notsup</c> in case the chosen <c>Type</c> - is not supported by the underlying OpenSSL implementation.</p> + <p>May raise exception <c>error:notsup</c> in case the chosen <c>Type</c> + is not supported by the underlying libcrypto implementation.</p> </desc> </func> <func> - <name>hash_update(Context, Data) -> NewContext</name> + <name name="hash_update" arity="2" since="OTP R15B02"/> <fsummary></fsummary> - <type> - <v>Data = iodata()</v> - </type> <desc> <p>Updates the digest represented by <c>Context</c> using the given <c>Data</c>. <c>Context</c> must have been generated using <seealso marker="#hash_init-1">hash_init</seealso> @@ -358,12 +685,10 @@ or <seealso marker="#hash_final-1">hash_final</seealso>.</p> </desc> </func> + <func> - <name>hash_final(Context) -> Digest</name> + <name name="hash_final" arity="1" since="OTP R15B02"/> <fsummary></fsummary> - <type> - <v>Digest = binary()</v> - </type> <desc> <p>Finalizes the hash operation referenced by <c>Context</c> returned from a previous call to <seealso marker="#hash_update-2">hash_update</seealso>. @@ -373,16 +698,9 @@ </func> <func> - <name>hmac(Type, Key, Data) -> Mac</name> - <name>hmac(Type, Key, Data, MacLength) -> Mac</name> + <name name="hmac" arity="3" since="OTP R16B"/> + <name name="hmac" arity="4" since="OTP R16B"/> <fsummary></fsummary> - <type> - <v>Type = hash_algorithms() - except ripemd160</v> - <v>Key = iodata()</v> - <v>Data = iodata()</v> - <v>MacLength = integer()</v> - <v>Mac = binary()</v> - </type> <desc> <p>Computes a HMAC of type <c>Type</c> from <c>Data</c> using <c>Key</c> as the authentication key.</p> <p><c>MacLength</c> @@ -391,13 +709,8 @@ </func> <func> - <name>hmac_init(Type, Key) -> Context</name> + <name name="hmac_init" arity="2" since="OTP R14B03"/> <fsummary></fsummary> - <type> - <v>Type = hash_algorithms() - except ripemd160</v> - <v>Key = iodata()</v> - <v>Context = binary()</v> - </type> <desc> <p>Initializes the context for streaming HMAC operations. <c>Type</c> determines which hash function to use in the HMAC operation. <c>Key</c> is the authentication @@ -406,15 +719,11 @@ </func> <func> - <name>hmac_update(Context, Data) -> NewContext</name> + <name name="hmac_update" arity="2" since="OTP R14B03"/> <fsummary></fsummary> - <type> - <v>Context = NewContext = binary()</v> - <v>Data = iodata()</v> - </type> <desc> <p>Updates the HMAC represented by <c>Context</c> using the given <c>Data</c>. <c>Context</c> - must have been generated using an HMAC init function (such as + must have been generated using an HMAC init function (such as <seealso marker="#hmac_init-2">hmac_init</seealso>). <c>Data</c> can be any length. <c>NewContext</c> must be passed into the next call to <c>hmac_update</c> or to one of the functions <seealso marker="#hmac_final-1">hmac_final</seealso> and @@ -424,16 +733,13 @@ call to hmac_update or hmac_final. The semantics of reusing old contexts in any way is undefined and could even crash the VM in earlier releases. The reason for this limitation is a lack of support in the underlying - OpenSSL API.</p></warning> + libcrypto API.</p></warning> </desc> </func> <func> - <name>hmac_final(Context) -> Mac</name> + <name name="hmac_final" arity="1" since="OTP R14B03"/> <fsummary></fsummary> - <type> - <v>Context = Mac = binary()</v> - </type> <desc> <p>Finalizes the HMAC operation referenced by <c>Context</c>. The size of the resultant MAC is determined by the type of hash function used to generate it.</p> @@ -441,12 +747,8 @@ </func> <func> - <name>hmac_final_n(Context, HashLen) -> Mac</name> + <name name="hmac_final_n" arity="2" since="OTP R14B03"/> <fsummary></fsummary> - <type> - <v>Context = Mac = binary()</v> - <v>HashLen = non_neg_integer()</v> - </type> <desc> <p>Finalizes the HMAC operation referenced by <c>Context</c>. <c>HashLen</c> must be greater than zero. <c>Mac</c> will be a binary with at most <c>HashLen</c> bytes. Note that if HashLen is greater than the actual number of bytes returned from the underlying hash, the returned hash will have fewer than <c>HashLen</c> bytes.</p> @@ -454,13 +756,57 @@ </func> <func> - <name>info_lib() -> [{Name,VerNum,VerStr}]</name> + <name name="cmac" arity="3" since="OTP 20.0"/> + <name name="cmac" arity="4" since="OTP 20.0"/> + <fsummary>Calculates the Cipher-based Message Authentication Code.</fsummary> + <desc> + <p>Computes a CMAC of type <c>Type</c> from <c>Data</c> using + <c>Key</c> as the authentication key.</p> <p><c>MacLength</c> + will limit the size of the resultant <c>Mac</c>.</p> + </desc> + </func> + + <func> + <name name="info_fips" arity="0" since="OTP 20.0"/> + <fsummary>Provides information about the FIPS operating status.</fsummary> + <desc> + <p>Provides information about the FIPS operating status of + crypto and the underlying libcrypto library. If crypto was built + with FIPS support this can be either <c>enabled</c> (when + running in FIPS mode) or <c>not_enabled</c>. For other builds + this value is always <c>not_supported</c>. + </p> + <p>See <seealso marker="#enable_fips_mode-1">enable_fips_mode/1</seealso> about how to enable + FIPS mode. + </p> + <warning> + <p>In FIPS mode all non-FIPS compliant algorithms are + disabled and raise exception <c>error:notsup</c>. Check + <seealso marker="#supports-0">supports</seealso> that in + FIPS mode returns the restricted list of available + algorithms.</p> + </warning> + </desc> + </func> + + <func> + <name name="enable_fips_mode" arity="1" since="OTP 21.1"/> + <fsummary>Change FIPS mode.</fsummary> + <desc> + <p>Enables (<c>Enable = true</c>) or disables (<c>Enable = false</c>) FIPS mode. Returns <c>true</c> if + the operation was successful or <c>false</c> otherwise. + </p> + <p>Note that to enable FIPS mode succesfully, OTP must be built with the configure option <c>--enable-fips</c>, + and the underlying libcrypto must also support FIPS. + </p> + <p>See also <seealso marker="#info_fips-0">info_fips/0</seealso>. + </p> + </desc> + </func> + + <func> + <name name="info_lib" arity="0" since=""/> <fsummary>Provides information about the libraries used by crypto.</fsummary> - <type> - <v>Name = binary()</v> - <v>VerNum = integer()</v> - <v>VerStr = binary()</v> - </type> <desc> <p>Provides the name and version of the libraries used by crypto.</p> <p><c>Name</c> is the name of the library. <c>VerNum</c> is @@ -468,57 +814,50 @@ scheme. <c>VerStr</c> contains a text variant of the version.</p> <pre> > <input>info_lib().</input> -[{<<"OpenSSL">>,9469983,<<"OpenSSL 0.9.8a 11 Oct 2005">>}] +[{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c 10 Nov 2016"">>}] </pre> <note><p> From OTP R16 the <em>numeric version</em> represents the version of the OpenSSL <em>header files</em> (<c>openssl/opensslv.h</c>) used when crypto was compiled. - The text variant represents the OpenSSL library used at runtime. + The text variant represents the libcrypto library used at runtime. In earlier OTP versions both numeric and text was taken from the library. </p></note> </desc> </func> <func> - <name>mod_pow(N, P, M) -> Result</name> + <name name="mod_pow" arity="3" since="OTP R16B01"/> <fsummary>Computes the function: N^P mod M</fsummary> - <type> - <v>N, P, M = binary() | integer()</v> - <v>Result = binary() | error</v> - </type> <desc> <p>Computes the function <c>N^P mod M</c>.</p> </desc> </func> <func> - <name>next_iv(Type, Data) -> NextIVec</name> - <name>next_iv(Type, Data, IVec) -> NextIVec</name> - <fsummary></fsummary> - <type> - <v>Type = des_cbc | des3_cbc | aes_cbc | des_cfb</v> - <v>Data = iodata()</v> - <v>IVec = NextIVec = binary()</v> - </type> - <desc> - <p>Returns the initialization vector to be used in the next - iteration of encrypt/decrypt of type <c>Type</c>. <c>Data</c> is the - encrypted data from the previous iteration step. The <c>IVec</c> - argument is only needed for <c>des_cfb</c> as the vector used - in the previous iteration step.</p> - </desc> + <name name="next_iv" arity="2" since="OTP R16B01"/> + <name name="next_iv" arity="3" since="OTP R16B01"/> + <fsummary></fsummary> + <desc> + <p>Returns the initialization vector to be used in the next + iteration of encrypt/decrypt of type <c>Type</c>. <c>Data</c> is the + encrypted data from the previous iteration step. The <c>IVec</c> + argument is only needed for <c>des_cfb</c> as the vector used + in the previous iteration step.</p> + </desc> + </func> + + <func> + <name name="poly1305" arity="2" since="OTP 21.1"/> + <fsummary></fsummary> + <desc> + <p>Computes a POLY1305 message authentication code (<c>Mac</c>) from <c>Data</c> using + <c>Key</c> as the authentication key.</p> + </desc> </func> <func> - <name>private_decrypt(Type, CipherText, PrivateKey, Padding) -> PlainText</name> + <name name="private_decrypt" arity="4" since="OTP R16B01"/> <fsummary>Decrypts CipherText using the private Key.</fsummary> - <type> - <v>Type = rsa</v> - <v>CipherText = binary()</v> - <v>PrivateKey = rsa_private()</v> - <v>Padding = rsa_pkcs1_padding | rsa_pkcs1_oaep_padding | rsa_no_padding</v> - <v>PlainText = binary()</v> - </type> <desc> <p>Decrypts the <c>CipherText</c>, encrypted with <seealso marker="#public_encrypt-4">public_encrypt/4</seealso> (or equivalent function) @@ -529,21 +868,10 @@ </p> </desc> </func> - + <func> - <name>private_encrypt(Type, PlainText, PrivateKey, Padding) -> CipherText</name> + <name name="private_encrypt" arity="4" since="OTP R16B01"/> <fsummary>Encrypts PlainText using the private Key.</fsummary> - <type> - <v>Type = rsa</v> - <v>PlainText = binary()</v> - <d> The size of the <c>PlainText</c> must be less - than <c>byte_size(N)-11</c> if <c>rsa_pkcs1_padding</c> is - used, and <c>byte_size(N)</c> if <c>rsa_no_padding</c> is - used, where N is public modulus of the RSA key.</d> - <v>PrivateKey = rsa_private()</v> - <v>Padding = rsa_pkcs1_padding | rsa_no_padding</v> - <v>CipherText = binary()</v> - </type> <desc> <p>Encrypts the <c>PlainText</c> using the <c>PrivateKey</c> and returns the ciphertext. This is a low level signature operation @@ -553,16 +881,10 @@ </p> </desc> </func> + <func> - <name>public_decrypt(Type, CipherText, PublicKey, Padding) -> PlainText</name> + <name name="public_decrypt" arity="4" since="OTP R16B01"/> <fsummary>Decrypts CipherText using the public Key.</fsummary> - <type> - <v>Type = rsa</v> - <v>CipherText = binary()</v> - <v>PublicKey = rsa_public() </v> - <v>Padding = rsa_pkcs1_padding | rsa_no_padding</v> - <v>PlainText = binary()</v> - </type> <desc> <p>Decrypts the <c>CipherText</c>, encrypted with <seealso marker="#private_encrypt-4">private_encrypt/4</seealso>(or equivalent function) @@ -575,19 +897,8 @@ </func> <func> - <name>public_encrypt(Type, PlainText, PublicKey, Padding) -> CipherText</name> + <name name="public_encrypt" arity="4" since="OTP R16B01"/> <fsummary>Encrypts PlainText using the public Key.</fsummary> - <type> - <v>Type = rsa</v> - <v>PlainText = binary()</v> - <d> The size of the <c>PlainText</c> must be less - than <c>byte_size(N)-11</c> if <c>rsa_pkcs1_padding</c> is - used, and <c>byte_size(N)</c> if <c>rsa_no_padding</c> is - used, where N is public modulus of the RSA key.</d> - <v>PublicKey = rsa_public()</v> - <v>Padding = rsa_pkcs1_padding | rsa_pkcs1_oaep_padding | rsa_no_padding</v> - <v>CipherText = binary()</v> - </type> <desc> <p>Encrypts the <c>PlainText</c> (message digest) using the <c>PublicKey</c> and returns the <c>CipherText</c>. This is a low level signature operation @@ -598,22 +909,20 @@ </func> <func> - <name>rand_seed(Seed) -> ok</name> + <name name="rand_seed" arity="1" since="OTP 17.0"/> <fsummary>Set the seed for random bytes generation</fsummary> - <type> - <v>Seed = binary()</v> - </type> <desc> <p>Set the seed for PRNG to the given binary. This calls the - RAND_seed function from openssl. Only use this if the system - you are running on does not have enough "randomness" built in. - Normally this is when <seealso marker="#strong_rand_bytes/1"> - strong_rand_bytes/1</seealso> returns <c>low_entropy</c></p> + RAND_seed function from openssl. Only use this if the system + you are running on does not have enough "randomness" built in. + Normally this is when + <seealso marker="#strong_rand_bytes/1">strong_rand_bytes/1</seealso> + raises <c>error:low_entropy</c></p> </desc> </func> <func> - <name>rand_uniform(Lo, Hi) -> N</name> + <name since="">rand_uniform(Lo, Hi) -> N</name> <fsummary>Generate a random number</fsummary> <type> <v>Lo, Hi, N = integer()</v> @@ -626,34 +935,15 @@ </func> <func> - <name>sign(Algorithm, DigestType, Msg, Key) -> binary()</name> - <fsummary> Create digital signature.</fsummary> - <type> - <v>Algorithm = rsa | dss | ecdsa </v> - <v>Msg = binary() | {digest,binary()}</v> - <d>The msg is either the binary "cleartext" data to be - signed or it is the hashed value of "cleartext" i.e. the - digest (plaintext).</d> - <v>DigestType = digest_type()</v> - <v>Key = rsa_private() | dss_private() | [ecdh_private(),ecdh_params()]</v> - </type> - <desc> - <p>Creates a digital signature.</p> - <p>Algorithm <c>dss</c> can only be used together with digest type - <c>sha</c>.</p> - <p>See also <seealso marker="public_key:public_key#sign-3">public_key:sign/3</seealso>.</p> - </desc> - </func> - - <func> - <name>start() -> ok</name> + <name name="start" arity="0" since=""/> <fsummary> Equivalent to application:start(crypto). </fsummary> <desc> <p> Equivalent to application:start(crypto).</p> </desc> </func> + <func> - <name>stop() -> ok</name> + <name name="stop" arity="0" since=""/> <fsummary> Equivalent to application:stop(crypto).</fsummary> <desc> <p> Equivalent to application:stop(crypto).</p> @@ -661,60 +951,206 @@ </func> <func> - <name>strong_rand_bytes(N) -> binary()</name> + <name name="strong_rand_bytes" arity="1" since="OTP R14B03"/> <fsummary>Generate a binary of random bytes</fsummary> - <type> - <v>N = integer()</v> - </type> <desc> <p>Generates N bytes randomly uniform 0..255, and returns the result in a binary. Uses a cryptographically secure prng seeded and periodically mixed with operating system provided entropy. By default this is the <c>RAND_bytes</c> method from OpenSSL.</p> - <p>May throw exception <c>low_entropy</c> in case the random generator + <p>May raise exception <c>error:low_entropy</c> in case the random generator failed due to lack of secure "randomness".</p> </desc> </func> + <func> - <name>stream_init(Type, Key) -> State</name> - <fsummary></fsummary> + <name name="rand_seed" arity="0" since="OTP 20.0"/> + <fsummary>Strong random number generation plugin state</fsummary> + <desc> + <p> + Creates state object for + <seealso marker="stdlib:rand">random number generation</seealso>, + in order to generate cryptographically strong random numbers + (based on OpenSSL's <c>BN_rand_range</c>), + and saves it in the process dictionary before returning it as well. + See also + <seealso marker="stdlib:rand#seed-1">rand:seed/1</seealso> and + <seealso marker="#rand_seed_s-0">rand_seed_s/0</seealso>. + </p> + <p> + When using the state object from this function the + <seealso marker="stdlib:rand">rand</seealso> functions using it + may raise exception <c>error:low_entropy</c> in case the random generator + failed due to lack of secure "randomness". + </p> + <p><em>Example</em></p> + <pre> +_ = crypto:rand_seed(), +_IntegerValue = rand:uniform(42), % [1; 42] +_FloatValue = rand:uniform(). % [0.0; 1.0[</pre> + </desc> + </func> + + <func> + <name name="rand_seed_s" arity="0" since="OTP 20.0"/> + <fsummary>Strong random number generation plugin state</fsummary> + <desc> + <p> + Creates state object for + <seealso marker="stdlib:rand">random number generation</seealso>, + in order to generate cryptographically strongly random numbers + (based on OpenSSL's <c>BN_rand_range</c>). + See also + <seealso marker="stdlib:rand#seed_s-1">rand:seed_s/1</seealso>. + </p> + <p> + When using the state object from this function the + <seealso marker="stdlib:rand">rand</seealso> functions using it + may raise exception <c>error:low_entropy</c> in case the random generator + failed due to lack of secure "randomness". + </p> + <note> + <p> + The state returned from this function can not be used + to get a reproducable random sequence as from + the other + <seealso marker="stdlib:rand">rand</seealso> + functions, + since reproducability does not match cryptographically safe. + </p> + <p> + The only supported usage is to generate one distinct + random sequence from this start state. + </p> + </note> + </desc> + </func> + + <func> + <name since="OTP 21.0">rand_seed_alg(Alg) -> rand:state()</name> + <fsummary>Strong random number generation plugin state</fsummary> <type> - <v>Type = rc4 </v> - <v>State = opaque() </v> - <v>Key = iodata()</v> + <v>Alg = crypto | crypto_cache</v> </type> <desc> + <marker id="rand_seed_alg-1" /> + <p> + Creates state object for + <seealso marker="stdlib:rand">random number generation</seealso>, + in order to generate cryptographically strong random numbers. + See also + <seealso marker="stdlib:rand#seed-1">rand:seed/1</seealso> and + <seealso marker="#rand_seed_alg_s-1">rand_seed_alg_s/1</seealso>. + </p> + <p> + When using the state object from this function the + <seealso marker="stdlib:rand">rand</seealso> functions using it + may raise exception <c>error:low_entropy</c> in case the random generator + failed due to lack of secure "randomness". + </p> + <p> + The cache size can be changed from its default value using the + <seealso marker="crypto_app"> + crypto app's + </seealso> configuration parameter <c>rand_cache_size</c>. + </p> + <p><em>Example</em></p> + <pre> +_ = crypto:rand_seed_alg(crypto_cache), +_IntegerValue = rand:uniform(42), % [1; 42] +_FloatValue = rand:uniform(). % [0.0; 1.0[</pre> + </desc> + </func> + + <func> + <name since="OTP 21.0">rand_seed_alg_s(Alg) -> rand:state()</name> + <fsummary>Strong random number generation plugin state</fsummary> + <type> + <v>Alg = crypto | crypto_cache</v> + </type> + <desc> + <marker id="rand_seed_alg_s-1" /> + <p> + Creates state object for + <seealso marker="stdlib:rand">random number generation</seealso>, + in order to generate cryptographically strongly random numbers. + See also + <seealso marker="stdlib:rand#seed_s-1">rand:seed_s/1</seealso>. + </p> + <p> + If <c>Alg</c> is <c>crypto</c> this function behaves exactly like + <seealso marker="#rand_seed_s-0">rand_seed_s/0</seealso>. + </p> + <p> + If <c>Alg</c> is <c>crypto_cache</c> this function + fetches random data with OpenSSL's <c>RAND_bytes</c> + and caches it for speed using an internal word size + of 56 bits that makes calculations fast on 64 bit machines. + </p> + <p> + When using the state object from this function the + <seealso marker="stdlib:rand">rand</seealso> functions using it + may raise exception <c>error:low_entropy</c> in case the random generator + failed due to lack of secure "randomness". + </p> + <p> + The cache size can be changed from its default value using the + <seealso marker="crypto_app"> + crypto app's + </seealso> configuration parameter <c>rand_cache_size</c>. + </p> + <note> + <p> + The state returned from this function can not be used + to get a reproducable random sequence as from + the other + <seealso marker="stdlib:rand">rand</seealso> + functions, + since reproducability does not match cryptographically safe. + </p> + <p> + In fact since random data is cached some numbers may + get reproduced if you try, but this is unpredictable. + </p> + <p> + The only supported usage is to generate one distinct + random sequence from this start state. + </p> + </note> + </desc> + </func> + + <func> + <name name="stream_init" arity="2" since="OTP R16B01"/> + <fsummary></fsummary> + <desc> <p>Initializes the state for use in RC4 stream encryption <seealso marker="#stream_encrypt-2">stream_encrypt</seealso> and <seealso marker="#stream_decrypt-2">stream_decrypt</seealso></p> + <p>For keylengths see the + <seealso marker="crypto:algorithm_details#stream-ciphers">User's Guide</seealso>. + </p> </desc> </func> <func> - <name>stream_init(Type, Key, IVec) -> State</name> + <name name="stream_init" arity="3" since="OTP R16B01"/> <fsummary></fsummary> - <type> - <v>Type = aes_ctr </v> - <v>State = opaque() </v> - <v>Key = iodata()</v> - <v>IVec = binary()</v> - </type> <desc> <p>Initializes the state for use in streaming AES encryption using Counter mode (CTR). <c>Key</c> is the AES key and must be either 128, 192, or 256 bits long. <c>IVec</c> is an arbitrary initializing vector of 128 bits (16 bytes). This state is for use with <seealso marker="#stream_encrypt-2">stream_encrypt</seealso> and <seealso marker="#stream_decrypt-2">stream_decrypt</seealso>.</p> + <p>For keylengths and iv-sizes see the + <seealso marker="crypto:algorithm_details#stream-ciphers">User's Guide</seealso>. + </p> </desc> </func> <func> - <name>stream_encrypt(State, PlainText) -> { NewState, CipherText}</name> + <name name="stream_encrypt" arity="2" since="OTP R16B01"/> <fsummary></fsummary> - <type> - <v>Text = iodata()</v> - <v>CipherText = binary()</v> - </type> <desc> <p>Encrypts <c>PlainText</c> according to the stream cipher <c>Type</c> specified in stream_init/3. <c>Text</c> can be any number of bytes. The initial <c>State</c> is created using @@ -724,12 +1160,8 @@ </func> <func> - <name>stream_decrypt(State, CipherText) -> { NewState, PlainText }</name> + <name name="stream_decrypt" arity="2" since="OTP R16B01"/> <fsummary></fsummary> - <type> - <v>CipherText = iodata()</v> - <v>PlainText = binary()</v> - </type> <desc> <p>Decrypts <c>CipherText</c> according to the stream cipher <c>Type</c> specified in stream_init/3. <c>PlainText</c> can be any number of bytes. The initial <c>State</c> is created using @@ -739,57 +1171,57 @@ </func> <func> - <name>supports() -> AlgorithmList </name> + <name name="supports" arity="0" since="OTP R16B01"/> <fsummary>Provide a list of available crypto algorithms.</fsummary> - <type> - <v> AlgorithmList = [{hashs, [hash_algorithms()]}, - {ciphers, [cipher_algorithms()]}, - {public_keys, [public_key_algorithms()]} - </v> - </type> <desc> <p> Can be used to determine which crypto algorithms that are supported - by the underlying OpenSSL library</p> + by the underlying libcrypto library</p> + <p>Note: the <c>rsa_opts</c> entry is in an experimental state and may change or be removed without notice. + No guarantee for the accuarcy of the rsa option's value list should be assumed. + </p> </desc> </func> <func> - <name>ec_curves() -> EllipticCurveList </name> + <name name="ec_curves" arity="0" since="OTP 17.0"/> <fsummary>Provide a list of available named elliptic curves.</fsummary> - <type> - <v>EllipticCurveList = [ec_named_curve()]</v> - </type> <desc> <p>Can be used to determine which named elliptic curves are supported.</p> </desc> </func> <func> - <name>ec_curve(NamedCurve) -> EllipticCurve </name> + <name name="ec_curve" arity="1" since="OTP 17.0"/> <fsummary>Get the defining parameters of a elliptic curve.</fsummary> - <type> - <v>NamedCurve = ec_named_curve()</v> - <v>EllipticCurve = ec_explicit_curve()</v> - </type> <desc> <p>Return the defining parameters of a elliptic curve.</p> </desc> </func> - <func> - <name>verify(Algorithm, DigestType, Msg, Signature, Key) -> boolean()</name> + <func> + <name name="sign" arity="4" since="OTP R16B01"/> + <name name="sign" arity="5" since="OTP 20.1"/> + <fsummary> Create digital signature.</fsummary> + <desc> + <p>Creates a digital signature.</p> + <p>The msg is either the binary "cleartext" data to be + signed or it is the hashed value of "cleartext" i.e. the + digest (plaintext).</p> + <p>Algorithm <c>dss</c> can only be used together with digest type + <c>sha</c>.</p> + <p>See also <seealso marker="public_key:public_key#sign-3">public_key:sign/3</seealso>.</p> + </desc> + </func> + + <func> + <name name="verify" arity="5" since="OTP R16B01"/> + <name name="verify" arity="6" since="OTP 20.1"/> <fsummary>Verifies a digital signature.</fsummary> - <type> - <v> Algorithm = rsa | dss | ecdsa </v> - <v>Msg = binary() | {digest,binary()}</v> - <d>The msg is either the binary "cleartext" data - or it is the hashed value of "cleartext" i.e. the digest (plaintext).</d> - <v>DigestType = digest_type()</v> - <v>Signature = binary()</v> - <v>Key = rsa_public() | dss_public() | [ecdh_public(),ecdh_params()]</v> - </type> <desc> <p>Verifies a digital signature</p> + <p>The msg is either the binary "cleartext" data to be + signed or it is the hashed value of "cleartext" i.e. the + digest (plaintext).</p> <p>Algorithm <c>dss</c> can only be used together with digest type <c>sha</c>.</p> @@ -797,78 +1229,317 @@ </desc> </func> + <!-- Engine functions --> + <func> + <name name="privkey_to_pubkey" arity="2" since="OTP 20.2"/> + <fsummary>Fetches a public key from an Engine stored private key.</fsummary> + <desc> + <p>Fetches the corresponding public key from a private key stored in an Engine. + The key must be of the type indicated by the Type parameter. + </p> + </desc> + </func> + + <func> + <name name="engine_get_all_methods" arity="0" since="OTP 20.2"/> + <fsummary>Return list of all possible engine methods</fsummary> + <desc> + <p> + Returns a list of all possible engine methods. + </p> + <p> + May raise exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="engine_load" arity="3" since="OTP 20.2"/> + <fsummary>Dynamical load an encryption engine</fsummary> + <desc> + <p> + Loads the OpenSSL engine given by <c>EngineId</c> if it is available and then returns ok and + an engine handle. This function is the same as calling <c>engine_load/4</c> with + <c>EngineMethods</c> set to a list of all the possible methods. An error tuple is + returned if the engine can't be loaded. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="engine_load" arity="4" since="OTP 20.2"/> + <fsummary>Dynamical load an encryption engine</fsummary> + <desc> + <p> + Loads the OpenSSL engine given by <c>EngineId</c> if it is available and then returns ok and + an engine handle. An error tuple is returned if the engine can't be loaded. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="engine_unload" arity="1" since="OTP 20.2"/> + <fsummary>Dynamical load an encryption engine</fsummary> + <desc> + <p> + Unloads the OpenSSL engine given by <c>Engine</c>. + An error tuple is returned if the engine can't be unloaded. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameter is in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="engine_by_id" arity="1" since="OTP 21.0.6"/> + <fsummary>Get a reference to an already loaded engine</fsummary> + <desc> + <p> + Get a reference to an already loaded engine with <c>EngineId</c>. + An error tuple is returned if the engine can't be unloaded. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameter is in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="engine_ctrl_cmd_string" arity="3" since="OTP 20.2"/> + <fsummary>Sends ctrl commands to an OpenSSL engine</fsummary> + <desc> + <p> + Sends ctrl commands to the OpenSSL engine given by <c>Engine</c>. + This function is the same as calling <c>engine_ctrl_cmd_string/4</c> with + <c>Optional</c> set to <c>false</c>. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + </desc> + </func> + + <func> + <name name="engine_ctrl_cmd_string" arity="4" since="OTP 20.2"/> + <fsummary>Sends ctrl commands to an OpenSSL engine</fsummary> + <desc> + <p> + Sends ctrl commands to the OpenSSL engine given by <c>Engine</c>. + <c>Optional</c> is a boolean argument that can relax the semantics of the function. + If set to <c>true</c> it will only return failure if the ENGINE supported the given + command name but failed while executing it, if the ENGINE doesn't support the command + name it will simply return success without doing anything. In this case we assume + the user is only supplying commands specific to the given ENGINE so we set this to + <c>false</c>. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + </desc> + </func> + + <func> + <name name="engine_add" arity="1" since="OTP 21.0.6"/> + <fsummary>Add engine to OpenSSL internal list</fsummary> + <desc> + <p>Add the engine to OpenSSL's internal list.</p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + </desc> + </func> + + <func> + <name name="engine_remove" arity="1" since="OTP 21.0.6"/> + <fsummary>Remove engine to OpenSSL internal list</fsummary> + <desc> + <p>Remove the engine from OpenSSL's internal list.</p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + </desc> + </func> + + <func> + <name name="engine_get_id" arity="1" since="OTP 21.0.6"/> + <fsummary>Fetch engine ID</fsummary> + <desc> + <p>Return the ID for the engine, or an empty binary if there is no id set.</p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + </desc> + </func> + + <func> + <name name="engine_get_name" arity="1" since="OTP 21.0.6"/> + <fsummary>Fetch engine name</fsummary> + <desc> + <p>Return the name (eg a description) for the engine, or an empty binary if there is no name set.</p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + </desc> + </func> + + <func> + <name name="engine_list" arity="0" since="OTP 20.2"/> + <fsummary>List the known engine ids</fsummary> + <desc> + <p>List the id's of all engines in OpenSSL's internal list.</p> + <p> + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + <p> + May raise exception <c>error:notsup</c> in case engine functionality is not supported by the underlying + OpenSSL implementation. + </p> + </desc> + </func> + + <func> + <name name="ensure_engine_loaded" arity="2" since="OTP 21.0.6"/> + <fsummary>Ensure encryption engine just loaded once</fsummary> + <desc> + <p> + Loads the OpenSSL engine given by <c>EngineId</c> and the path to the dynamic library + implementing the engine. This function is the same as calling <c>ensure_engine_loaded/3</c> with + <c>EngineMethods</c> set to a list of all the possible methods. An error tuple is + returned if the engine can't be loaded. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="ensure_engine_loaded" arity="3" since="OTP 21.0.6"/> + <fsummary>Ensure encryption engine just loaded once</fsummary> + <desc> + <p> + Loads the OpenSSL engine given by <c>EngineId</c> and the path to the dynamic library + implementing the engine. This function differs from the normal engine_load in that sense it + also add the engine id to the internal list in OpenSSL. Then in the following calls to the function + it just fetch the reference to the engine instead of loading it again. + An error tuple is returned if the engine can't be loaded. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="ensure_engine_unloaded" arity="1" since="OTP 21.0.6"/> + <fsummary>Unload an engine loaded with the ensure function</fsummary> + <desc> + <p> + Unloads an engine loaded with the <c>ensure_engine_loaded</c> function. + It both removes the label from the OpenSSL internal engine list and unloads the engine. + This function is the same as calling <c>ensure_engine_unloaded/2</c> with + <c>EngineMethods</c> set to a list of all the possible methods. An error tuple is + returned if the engine can't be unloaded. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="ensure_engine_unloaded" arity="2" since="OTP 21.0.6"/> + <fsummary>Unload an engine loaded with the ensure function</fsummary> + <desc> + <p> + Unloads an engine loaded with the <c>ensure_engine_loaded</c> function. + It both removes the label from the OpenSSL internal engine list and unloads the engine. + An error tuple is returned if the engine can't be unloaded. + </p> + <p> + The function raises a <c>error:badarg</c> if the parameters are in wrong format. + It may also raise the exception <c>error:notsup</c> in case there is + no engine support in the underlying OpenSSL implementation. + </p> + <p> + See also the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + in the User's Guide. + </p> + </desc> + </func> + </funcs> - <!-- Maybe put this in the users guide --> - <!-- <section> --> - <!-- <title>DES in CBC mode</title> --> - <!-- <p>The Data Encryption Standard (DES) defines an algorithm for --> - <!-- encrypting and decrypting an 8 byte quantity using an 8 byte key --> - <!-- (actually only 56 bits of the key is used). --> - <!-- </p> --> - <!-- <p>When it comes to encrypting and decrypting blocks that are --> - <!-- multiples of 8 bytes various modes are defined (NIST SP --> - <!-- 800-38A). One of those modes is the Cipher Block Chaining (CBC) --> - <!-- mode, where the encryption of an 8 byte segment depend not only --> - <!-- of the contents of the segment itself, but also on the result of --> - <!-- encrypting the previous segment: the encryption of the previous --> - <!-- segment becomes the initializing vector of the encryption of the --> - <!-- current segment. --> - <!-- </p> --> - <!-- <p>Thus the encryption of every segment depends on the encryption --> - <!-- key (which is secret) and the encryption of the previous --> - <!-- segment, except the first segment which has to be provided with --> - <!-- an initial initializing vector. That vector could be chosen at --> - <!-- random, or be a counter of some kind. It does not have to be --> - <!-- secret. --> - <!-- </p> --> - <!-- <p>The following example is drawn from the old FIPS 81 standard --> - <!-- (replaced by NIST SP 800-38A), where both the plain text and the --> - <!-- resulting cipher text is settled. The following code fragment --> - <!-- returns `true'. --> - <!-- </p> --> - <!-- <pre><![CDATA[ --> - - <!-- Key = <<16#01,16#23,16#45,16#67,16#89,16#ab,16#cd,16#ef>>, --> - <!-- IVec = <<16#12,16#34,16#56,16#78,16#90,16#ab,16#cd,16#ef>>, --> - <!-- P = "Now is the time for all ", --> - <!-- C = crypto:des_cbc_encrypt(Key, IVec, P), --> - <!-- % Which is the same as --> - <!-- P1 = "Now is t", P2 = "he time ", P3 = "for all ", --> - <!-- C1 = crypto:des_cbc_encrypt(Key, IVec, P1), --> - <!-- C2 = crypto:des_cbc_encrypt(Key, C1, P2), --> - <!-- C3 = crypto:des_cbc_encrypt(Key, C2, P3), --> - - <!-- C = <<C1/binary, C2/binary, C3/binary>>, --> - <!-- C = <<16#e5,16#c7,16#cd,16#de,16#87,16#2b,16#f2,16#7c, --> - <!-- 16#43,16#e9,16#34,16#00,16#8c,16#38,16#9c,16#0f, --> - <!-- 16#68,16#37,16#88,16#49,16#9a,16#7c,16#05,16#f6>>, --> - <!-- <<"Now is the time for all ">> == --> - <!-- crypto:des_cbc_decrypt(Key, IVec, C). --> - <!-- ]]></pre> --> - <!-- <p>The following is true for the DES CBC mode. For all --> - <!-- decompositions <c>P1 ++ P2 = P</c> of a plain text message --> - <!-- <c>P</c> (where the length of all quantities are multiples of 8 --> - <!-- bytes), the encryption <c>C</c> of <c>P</c> is equal to <c>C1 ++ --> - <!-- C2</c>, where <c>C1</c> is obtained by encrypting <c>P1</c> with --> - <!-- <c>Key</c> and the initializing vector <c>IVec</c>, and where --> - <!-- <c>C2</c> is obtained by encrypting <c>P2</c> with <c>Key</c> --> - <!-- and the initializing vector <c>last8(C1)</c>, --> - <!-- where <c>last(Binary)</c> denotes the last 8 bytes of the --> - <!-- binary <c>Binary</c>. --> - <!-- </p> --> - <!-- <p>Similarly, for all decompositions <c>C1 ++ C2 = C</c> of a --> - <!-- cipher text message <c>C</c> (where the length of all quantities --> - <!-- are multiples of 8 bytes), the decryption <c>P</c> of <c>C</c> --> - <!-- is equal to <c>P1 ++ P2</c>, where <c>P1</c> is obtained by --> - <!-- decrypting <c>C1</c> with <c>Key</c> and the initializing vector --> - <!-- <c>IVec</c>, and where <c>P2</c> is obtained by decrypting --> - <!-- <c>C2</c> with <c>Key</c> and the initializing vector --> - <!-- <c>last8(C1)</c>, where <c>last8(Binary)</c> is as above. --> - <!-- </p> --> - <!-- <p>For DES3 (which uses three 64 bit keys) the situation is the --> - <!-- same. --> - <!-- </p> --> - <!-- </section> --> -</erlref> +</erlref> diff --git a/lib/crypto/doc/src/crypto_app.xml b/lib/crypto/doc/src/crypto_app.xml index 2b9e505988..8296b1bc77 100644 --- a/lib/crypto/doc/src/crypto_app.xml +++ b/lib/crypto/doc/src/crypto_app.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1999</year> - <year>2016</year> + <year>2017</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -41,14 +41,55 @@ <section> <title>DEPENDENCIES</title> - <p>The current crypto implementation uses nifs to interface OpenSSLs crypto library - and requires <em>OpenSSL</em> package version 0.9.8 or higher.</p> + <p>The current crypto implementation uses nifs to interface + OpenSSLs crypto library and may work with limited functionality + with as old versions as <em>OpenSSL</em> 0.9.8c. + FIPS mode support requires at least + version 1.0.1 and a FIPS capable OpenSSL installation. We recommend using a + version that is officially supported by the OpenSSL project. API compatible backends like + LibreSSL should also work.</p> + <p>Source releases of OpenSSL can be downloaded from the <url href="http://www.openssl.org">OpenSSL</url> project home page, or mirror sites listed there. </p> </section> <section> + <title>CONFIGURATION</title> + <p>The following configuration parameters are defined for the + crypto application. See <c>app(3)</c> for more information about + configuration parameters.</p> + <taglist> + <tag><c>fips_mode = boolean()</c></tag> + <item> + <p>Specifies whether to run crypto in FIPS mode. This setting + will take effect when the nif module is loaded. If FIPS mode + is requested but not available at run time the nif module and + thus the crypto module will fail to load. This mechanism + prevents the accidental use of non-validated algorithms.</p> + </item> + <tag><c>rand_cache_size = integer()</c></tag> + <item> + <p> + Sets the cache size in bytes to use by + <seealso marker="crypto#rand_seed_alg-1"> + <c>crypto:rand_seed_alg(crypto_cache)</c> + </seealso> and + <seealso marker="crypto#rand_seed_alg_s-1"> + <c>crypto:rand_seed_alg_s(crypto_cache)</c> + </seealso>. + This parameter is read when a seed function is called, + and then kept in generators state object. It has a rather + small default value that causes reads of strong random bytes + about once per hundred calls for a random value. + The set value is rounded up to an integral number of words + of the size these seed functions use. + </p> + </item> + </taglist> + </section> + + <section> <title>SEE ALSO</title> <p>application(3)</p> </section> diff --git a/lib/crypto/doc/src/engine_keys.xml b/lib/crypto/doc/src/engine_keys.xml new file mode 100644 index 0000000000..5ac690eb90 --- /dev/null +++ b/lib/crypto/doc/src/engine_keys.xml @@ -0,0 +1,129 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2017</year><year>2018</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>Engine Stored Keys</title> + <prepared>Hans Nilsson</prepared> + <date>2017-11-10</date> + <file>engine_keys.xml</file> + </header> + <p> + <marker id="engine_key"></marker> + This chapter describes the support in the crypto application for using public and private keys stored in encryption engines. + </p> + + <section> + <title>Background</title> + <p> + <url href="https://www.openssl.org/">OpenSSL</url> exposes an Engine API, which makes + it possible to plug in alternative implementations for some of the cryptographic + operations implemented by OpenSSL. + See the chapter <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + for details and how to load an Engine. + </p> + <p> + An engine could among other tasks provide a storage for + private or public keys. Such a storage could be made safer than the normal file system. Thoose techniques are not + described in this User's Guide. Here we concentrate on how to use private or public keys stored in + such an engine. + </p> + <p> + The storage engine must call <c>ENGINE_set_load_privkey_function</c> and <c>ENGINE_set_load_pubkey_function</c>. + See the OpenSSL cryptolib's <url href="https://www.openssl.org/docs/manpages.html">manpages</url>. + </p> + <p> + OTP/Crypto requires that the user provides two or three items of information about the key. The application used + by the user is usually on a higher level, for example in + <seealso marker="ssl:ssl#type-key">SSL</seealso>. If using + the crypto application directly, it is required that: + </p> + <list> + <item>an Engine is loaded, see the chapter on <seealso marker="crypto:engine_load#engine_load">Engine Load</seealso> + or the <seealso marker="crypto:crypto#engine_load-3">Reference Manual</seealso> + </item> + <item>a reference to a key in the Engine is available. This should be an Erlang string or binary and depends + on the Engine loaded + </item> + <item>an Erlang map is constructed with the Engine reference, the key reference and possibly a key passphrase if + needed by the Engine. See the <seealso marker="crypto:crypto#type-engine_key_ref">Reference Manual</seealso> for + details of the map. + </item> + </list> + </section> + + <section> + <title>Use Cases</title> + <section> + <title>Sign with an engine stored private key</title> + <p> + This example shows how to construct a key reference that is used in a sign operation. + The actual key is stored in the engine that is loaded at prompt 1. + </p> + <code> +1> {ok, EngineRef} = crypto:engine_load(....). +... +{ok,#Ref<0.2399045421.3028942852.173962>} +2> PrivKey = #{engine => EngineRef, + key_id => "id of the private key in Engine"}. +... +3> Signature = crypto:sign(rsa, sha, <<"The message">>, PrivKey). +<<65,6,125,254,54,233,84,77,83,63,168,28,169,214,121,76, + 207,177,124,183,156,185,160,243,36,79,125,230,231,...>> + </code> + </section> + + <section> + <title>Verify with an engine stored public key</title> + <p> + Here the signature and message in the last example is verifyed using the public key. + The public key is stored in an engine, only to exemplify that it is possible. The public + key could of course be handled openly as usual. + </p> + <code> +4> PublicKey = #{engine => EngineRef, + key_id => "id of the public key in Engine"}. +... +5> crypto:verify(rsa, sha, <<"The message">>, Signature, PublicKey). +true +6> + </code> + </section> + + <section> + <title>Using a password protected private key</title> + <p> + The same example as the first sign example, except that a password protects the key down in the Engine. + </p> + <code> +6> PrivKeyPwd = #{engine => EngineRef, + key_id => "id of the pwd protected private key in Engine", + password => "password"}. +... +7> crypto:sign(rsa, sha, <<"The message">>, PrivKeyPwd). +<<140,80,168,101,234,211,146,183,231,190,160,82,85,163, + 175,106,77,241,141,120,72,149,181,181,194,154,175,76, + 223,...>> +8> + </code> + + </section> + + </section> +</chapter> diff --git a/lib/crypto/doc/src/engine_load.xml b/lib/crypto/doc/src/engine_load.xml new file mode 100644 index 0000000000..5f7ccc784b --- /dev/null +++ b/lib/crypto/doc/src/engine_load.xml @@ -0,0 +1,129 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2017</year><year>2018</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>Engine Load</title> + <prepared>Lars Thorsén</prepared> + <date>2017-08-22</date> + <file>engine_load.xml</file> + </header> + <p> + <marker id="engine_load"></marker> + This chapter describes the support for loading encryption engines in the crypto application. + </p> + + <section> + <title>Background</title> + <p> + OpenSSL exposes an Engine API, which makes it possible to plug in alternative + implementations for some or all of the cryptographic operations implemented by OpenSSL. + When configured appropriately, OpenSSL calls the engine's implementation of these + operations instead of its own. + </p> + <p> + Typically, OpenSSL engines provide a hardware implementation of specific cryptographic + operations. The hardware implementation usually offers improved performance over its + software-based counterpart, which is known as cryptographic acceleration. + </p> + <note> + <p>The file name requirement on the engine dynamic library can differ between SSL versions.</p> + </note> + </section> + + <section> + <title>Use Cases</title> + <section> + <title>Dynamically load an engine from default directory</title> + <p> + If the engine is located in the OpenSSL/LibreSSL installation <c>engines</c> directory. + </p> + <code> +1> {ok, Engine} = crypto:engine_load(<<"otp_test_engine">>, [], []). + {ok, #Ref}</code> + </section> + + <section> + <title>Load an engine with the dynamic engine</title> + <p> + Load an engine with the help of the dynamic engine by giving the path to the library. + </p> + <code> + 2> {ok, Engine} = crypto:engine_load(<<"dynamic">>, + [{<<"SO_PATH">>, + <<"/some/path/otp_test_engine.so">>}, + {<<"ID">>, <<"MD5">>}, + <<"LOAD">>], + []). + {ok, #Ref}</code> + </section> + + <section> + <title>Load an engine and replace some methods</title> + <p> + Load an engine with the help of the dynamic engine and just + replace some engine methods. + </p> + <code> + 3> Methods = crypto:engine_get_all_methods() -- [engine_method_dh,engine_method_rand, +engine_method_ciphers,engine_method_digests, engine_method_store, +engine_method_pkey_meths, engine_method_pkey_asn1_meths]. +[engine_method_rsa,engine_method_dsa, + engine_method_ecdh,engine_method_ecdsa] + 4> {ok, Engine} = crypto:engine_load(<<"dynamic">>, + [{<<"SO_PATH">>, + <<"/some/path/otp_test_engine.so">>}, + {<<"ID">>, <<"MD5">>}, + <<"LOAD">>], + [], + Methods). + {ok, #Ref}</code> + </section> + + <section> + <title>Load with the ensure loaded function</title> + <p> + This function makes sure the engine is loaded just once and the ID is added to the internal + engine list of OpenSSL. The following calls to the function will check if the ID is loaded + and then just get a new reference to the engine. + </p> + <code> + 5> {ok, Engine} = crypto:ensure_engine_loaded(<<"MD5">>, + <<"/some/path/otp_test_engine.so">>). + {ok, #Ref}</code> + <p> + To unload it use crypto:ensure_engine_unloaded/1 which removes the ID from the internal list + before unloading the engine. + </p> + <code> + 6> crypto:ensure_engine_unloaded(<<"MD5">>). + ok</code> + </section> + + + + <section> + <title>List all engines currently loaded</title> + <code> + 5> crypto:engine_list(). +[<<"dynamic">>, <<"MD5">>]</code> + </section> + + </section> +</chapter> diff --git a/lib/crypto/doc/src/fascicules.xml b/lib/crypto/doc/src/fascicules.xml deleted file mode 100644 index cbc266cd30..0000000000 --- a/lib/crypto/doc/src/fascicules.xml +++ /dev/null @@ -1,18 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> - -<fascicules> - <fascicule file="usersguide" href="usersguide_frame.html" entry="no"> - User's Guide - </fascicule> - <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> - Reference Manual - </fascicule> - <fascicule file="release_notes" href="release_notes_frame.html" entry="no"> - Release Notes - </fascicule> - <fascicule file="" href="../../../../doc/print.html" entry="no"> - Off-Print - </fascicule> -</fascicules> - diff --git a/lib/crypto/doc/src/fips.xml b/lib/crypto/doc/src/fips.xml new file mode 100644 index 0000000000..3e5c2db1e0 --- /dev/null +++ b/lib/crypto/doc/src/fips.xml @@ -0,0 +1,211 @@ +<?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>FIPS mode</title> + <prepared>Dániel Szoboszlay</prepared> + <docno></docno> + <date>2014-05-12</date> + <rev>A</rev> + <file>fips.xml</file> + </header> + <p> + <marker id="fips"></marker> + This chapter describes FIPS mode support in the crypto application. + </p> + + <section> + <title>Background</title> + <p>OpenSSL can be built to provide FIPS 140-2 validated + cryptographic services. It is not the OpenSSL application that is + validated, but a special software component called the OpenSSL + FIPS Object Module. However applications do not use this Object + Module directly, but through the regular API of the OpenSSL + library.</p> + <p>The crypto application supports using OpenSSL in FIPS mode. In + this scenario only the validated algorithms provided by the Object + Module are accessible, other algorithms usually available in + OpenSSL (like md5) or implemented in the Erlang code (like SRP) + are disabled.</p> + </section> + + <section> + <title>Enabling FIPS mode</title> + <list type="ordered"> + <item> + <p>Build or install the FIPS Object Module and a FIPS enabled + OpenSSL library.</p> + <p>You should read and precisely follow the instructions of + the <url + href="http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf">Security + Policy</url> and <url + href="https://www.openssl.org/docs/fips/UserGuide-2.0.pdf">User + Guide</url>.</p> + <warning><p>It is very easy to build a working OpenSSL FIPS + Object Module and library from the source. However it <em>does + not</em> qualify as FIPS 140-2 validated if the numerous + restrictions in the Security Policy are not properly + followed.</p></warning> + </item> + <item> + <p>Configure and build Erlang/OTP with FIPS support:</p> + <pre> +$ <input>cd $ERL_TOP</input> +$ <input>./otp_build configure --enable-fips</input> +... +checking for FIPS_mode_set... yes +... +$ <input>make</input> + </pre> + <p>If <c>FIPS_mode_set</c> returns <c>no</c> the OpenSSL + library is not FIPS enabled and crypto won't support FIPS mode + either.</p> + </item> + <item> + <p>Set the <c>fips_mode</c> configuration setting of the + crypto application to <c>true</c> <em>before loading the + crypto module</em>.</p> + <p>The best place is in the <c>sys.config</c> system + configuration file of the release.</p> + </item> + <item> + Start and use the crypto application as usual. However take + care to avoid the non-FIPS validated algorithms, they will all + throw exception <c>not_supported</c>. + </item> + </list> + <p>Entering and leaving FIPS mode on a node already running crypto + is not supported. The reason is that OpenSSL is designed to + prevent an application requesting FIPS mode to end up accidentally + running in non-FIPS mode. If entering FIPS mode fails (e.g. the + Object Module is not found or is compromised) any subsequent use + of the OpenSSL API would terminate the emulator.</p> + <p>An on-the-fly FIPS mode change would thus have to be performed + in a critical section protected from any concurrently running + crypto operations. Furthermore in case of failure all crypto calls + would have to be disabled from the Erlang or nif code. This would + be too much effort put into this not too important feature.</p> + </section> + + <section> + <title>Incompatibilities with regular builds</title> + <p>The Erlang API of the crypto application is identical + regardless of building with or without FIPS support. However the + nif code internally uses a different OpenSSL API.</p> + <p>This means that the context (an opaque type) returned from + streaming crypto functions (<c>hash_(init|update|final)</c>, + <c>hmac_(init|update|final)</c> and + <c>stream_(init|encrypt|decrypt)</c>) is different and + incompatible with regular builds when compiling crypto with FIPS + support.</p> + </section> + + <section> + <title>Common caveats</title> + <p>In FIPS mode non-validated algorithms are disabled. This may + cause some unexpected problems in application relying on + crypto.</p> + <warning><p>Do not try to work around these problems by using + alternative implementations of the missing algorithms! An + application can only claim to be using a FIPS 140-2 validated + cryptographic module if it uses it exclusively for every + cryptographic operation.</p></warning> + + <section> + <title>Restrictions on key sizes</title> + <p>Although public key algorithms are supported in FIPS mode + they can only be used with secure key sizes. The Security Policy + requires the following minimum values: + </p> + <taglist> + <tag>RSA</tag><item>1024 bit</item> + <tag>DSS</tag><item>1024 bit</item> + <tag>EC algorithms</tag><item>160 bit</item> + </taglist> + </section> + + <section> + <title>Restrictions on elliptic curves</title> + <p>The Erlang API allows using arbitrary curve parameters, but + in FIPS mode only those allowed by the Security Policy shall be + used.</p> + </section> + + <section> + <title>Avoid md5 for hashing</title> + <p>Md5 is a popular choice as a hash function, but it is not + secure enough to be validated. Try to use sha instead wherever + possible.</p> + <p>For exceptional, non-cryptographic use cases one may consider + switching to <c>erlang:md5/1</c> as well.</p> + </section> + + <section> + <title>Certificates and encrypted keys</title> + <p>As md5 is not available in FIPS mode it is only possible to + use certificates that were signed using sha hashing. When + validating an entire certificate chain all certificates + (including the root CA's) must comply with this rule.</p> + <p>For similar dependency on the md5 and des algorithms most + encrypted private keys in PEM format do not work + either. However, the PBES2 encryption scheme allows the use of + stronger FIPS verified algorithms which is a viable + alternative.</p> + </section> + + <section> + <title>SNMP v3 limitations</title> + <p>It is only possible to use <c>usmHMACSHAAuthProtocol</c> and + <c>usmAesCfb128Protocol</c> for authentication and privacy + respectively in FIPS mode. The snmp application however won't + restrict selecting disabled protocols in any way, and using them + would result in run time crashes.</p> + </section> + + <section> + <title>TLS 1.2 is required</title> + <p>All SSL and TLS versions prior to TLS 1.2 use a combination + of md5 and sha1 hashes in the handshake for various purposes:</p> + <list> + <item>Authenticating the integrity of the handshake + messages.</item> + <item>In the exchange of DH parameters in cipher suites + providing non-anonymous PFS (perfect forward secrecy).</item> + <item>In the PRF (pseud-random function) to generate keying + materials in cipher suites not using PFS.</item> + </list> + <p>OpenSSL handles these corner cases in FIPS mode, however the + Erlang crypto and ssl applications are not prepared for them and + therefore you are limited to TLS 1.2 in FIPS mode.</p> + <p>On the other hand it worth mentioning that at least all + cipher suites that would rely on non-validated algorithms are + automatically disabled in FIPS mode.</p> + <note><p>Certificates using weak (md5) digests may also cause + problems in TLS. Although TLS 1.2 has an extension for + specifying which type of signatures are accepted, and in FIPS + mode the ssl application will use it properly, most TLS + implementations ignore this extension and simply send whatever + certificates they were configured with.</p></note> + </section> + + </section> +</chapter> diff --git a/lib/crypto/doc/src/note.gif b/lib/crypto/doc/src/note.gif Binary files differdeleted file mode 100644 index 6fffe30419..0000000000 --- a/lib/crypto/doc/src/note.gif +++ /dev/null diff --git a/lib/crypto/doc/src/notes.xml b/lib/crypto/doc/src/notes.xml index 887aeca680..c0b302734e 100644 --- a/lib/crypto/doc/src/notes.xml +++ b/lib/crypto/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1999</year><year>2016</year> + <year>1999</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,578 @@ </header> <p>This document describes the changes made to the Crypto application.</p> +<section><title>Crypto 4.4.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixes a bug that caused <c>crypto:sign</c> and + <c>crypto:verify</c> to return the error message + <c>badarg</c> instead of <c>notsup</c> in one case. That + case was when signing or verifying with eddsa keys (that + is, ed15519 or ed448), but only when FIPS was supported + and enabled.</p> + <p> + Own Id: OTP-15634</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Added a crypto benchmark test suite.</p> + <p> + Own Id: OTP-15447</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Updated the RSA options part in the crypto application's + C-code, documentation and tests.</p> + <p> + Own Id: OTP-15302</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Added ed25519 and ed448 sign/verify.</p> + <p> + Requires OpenSSL 1.1.1 or higher as cryptolib under the + OTP application <c>crypto</c>.</p> + <p> + Own Id: OTP-15419 Aux Id: OTP-15094 </p> + </item> + <item> + <p> + Fixed valgrind warnings.</p> + <p> + Own Id: OTP-15467</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.3.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The RSA options <c>rsa_mgf1_md</c>, <c>rsa_oaep_md</c>, + and <c>rsa_oaep_label</c> were always disabled. They will + now be enabled when a suitable cryptolib is used.</p> + <p> + They are still experimental and may change without prior + notice.</p> + <p> + Own Id: OTP-15212 Aux Id: ERL-675, PR1899, PR838 </p> + </item> + <item> + <p> + The ciphers <c>aes_ige256</c> and <c>blowfish_cbc</c> had + naming issues in <c>crypto:next_iv/2</c>.</p> + <p> + Own Id: OTP-15283</p> + </item> + <item> + <p> + the <c>RSA_SSLV23_PADDING</c> is disabled if LibreSSL is + used as cryptlib. This is due to compilation problems.</p> + <p> + This will be investigated further in the future.</p> + <p> + Own Id: OTP-15303</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The supported named elliptic curves are now reported in + <c>crypto:supports/0</c> in a new entry tagged by + <c>'curves'</c>.</p> + <p> + The function <c>crypto:ec_curves/0</c> is kept for + compatibility.</p> + <p> + Own Id: OTP-14717 Aux Id: OTP-15244 </p> + </item> + <item> + <p> + The typing in the CRYPTO and PUBLIC_KEY applications are + reworked and a few mistakes are corrected.</p> + <p> + The documentation is now generated from the typing and + some clarifications are made.</p> + <p> + A new chapter on Algorithm Details such as key sizes and + availability is added to the CRYPTO User's Guide.</p> + <p> + Own Id: OTP-15134</p> + </item> + <item> + <p> + Support for SHA3 both as a separate hash and in HMAC is + now available if OpenSSL 1.1.1 or higher is used as + cryptolib.</p> + <p> + Available lengths are reported in the <c>'hashs'</c> + entry in <c>crypto:supports/0</c> as <c>sha3_*</c>.</p> + <p> + Own Id: OTP-15153</p> + </item> + <item> + <p> + The mac algorithm <c>poly1305</c> and the cipher + algorithm <c>chacha20</c> are now supported if OpenSSL + 1.1.1 or higher is used as cryptolib.</p> + <p> + Own Id: OTP-15164 Aux Id: OTP-15209 </p> + </item> + <item> + <p> + The key exchange Edward curves <c>x25519</c> and + <c>x448</c> are now supported if OpenSSL 1.1.1 or higher + is used as cryptolib.</p> + <p> + Own Id: OTP-15240 Aux Id: OTP-15133 </p> + </item> + <item> + <p> + The supported RSA options for sign/verify and + encrypt/decrypt are now reported in + <c>crypto:supports/0</c> in a new entry tagged by + '<c>rsa_opts</c>'.</p> + <p> + The exakt set is still experimental and may change + without prior notice.</p> + <p> + Own Id: OTP-15260</p> + </item> + <item> + <p> + The cipher <c>aes_ccm</c> is added.</p> + <p> + Own Id: OTP-15286</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.3.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Update the crypto engine functions to handle multiple + loads of an engine. </p> <p><c>engine_load/3/4</c> is + updated so it doesn't add the engine ID to OpenSSLs + internal list of engines which makes it possible to run + the engine_load more than once if it doesn't contain + global data.</p> <p>Added <c>ensure_engine_loaded/2/3</c> + which guarantees that the engine just is loaded once and + the following calls just returns a reference to it. This + is done by add the ID to the internal OpenSSL list and + check if it is already registered when the function is + called.</p> <p>Added <c>ensure_engine_unloaded/1/2</c> to + unload engines loaded with ensure_engine_loaded.</p> + <p>Then some more utility functions are added.</p> + <p><c>engine_add/1</c>, adds the engine to OpenSSL + internal list</p> <p><c>engine_remove/1</c>, remove the + engine from OpenSSL internal list</p> + <p><c>engine_get_id/1</c>, fetch the engines id</p> + <p><c>engine_get_name/1</c>, fetch the engine name</p> + <p> + Own Id: OTP-15233</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.3.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a node crash in <c>crypto:compute_key(ecdh, + ...)</c> when passing a wrongly typed Others + argument.</p> + <p> + Own Id: OTP-15194 Aux Id: ERL-673 </p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Removed two undocumented and erroneous functions + (<c>crypto:dh_generate_parameters/2</c> and + <c>crypto:dh_check/1</c>).</p> + <p> + Own Id: OTP-14956 Aux Id: ERL-579 </p> + </item> + <item> + <p> + Fixed bug causing VM crash if doing runtime upgrade of a + crypto module built against OpenSSL older than 0.9.8h. + Bug exists since OTP-20.2.</p> + <p> + Own Id: OTP-15088</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A new <c>rand</c> plugin algorithm has been implemented + in <c>crypto</c>, that is: <c>crypto_cache</c>. It uses + strong random bytes as randomness source and caches them + to get good speed. See <c>crypto:rand_seed_alg/1</c>.</p> + <p> + Own Id: OTP-13370 Aux Id: PR-1573 </p> + </item> + <item> + <p> + Diffie-Hellman key functions are re-written with the + EVP_PKEY api.</p> + <p> + Own Id: OTP-14864</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.2.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a node crash in <c>crypto:compute_key(ecdh, + ...)</c> when passing a wrongly typed Others + argument.</p> + <p> + Own Id: OTP-15194 Aux Id: ERL-673 </p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.2.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + If OPENSSL_NO_EC was set, the compilation of the crypto + nifs failed.</p> + <p> + Own Id: OTP-15073</p> + </item> + <item> + <p> + C-compile errors for LibreSSL 2.7.0 - 2.7.2 fixed</p> + <p> + Own Id: OTP-15074 Aux Id: ERL-618 </p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix build error caused by removed RSA padding functions + in LibreSSL >= 2.6.1</p> + <p> + Own Id: OTP-14873</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The compatibility function <c>void HMAC_CTX_free</c> in + <c>crypto.c</c> erroneously tried to return a value.</p> + <p> + Own Id: OTP-14720</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Rewrite public and private key encode/decode with EVP + api. New RSA padding options added. This is a modified + half of PR-838.</p> + <p> + Own Id: OTP-14446</p> + </item> + <item> + <p> + The crypto API is extended to use private/public keys + stored in an Engine for sign/verify or encrypt/decrypt + operations.</p> + <p> + The ssl application provides an API to use this new + engine concept in TLS.</p> + <p> + Own Id: OTP-14448</p> + </item> + <item> + <p> Add support to plug in alternative implementations + for some or all of the cryptographic operations supported + by the OpenSSL Engine API. When configured appropriately, + OpenSSL calls the engine's implementation of these + operations instead of its own. </p> + <p> + Own Id: OTP-14567</p> + </item> + <item> + <p> + Replaced a call of the OpenSSL deprecated function + <c>DH_generate_parameters</c> in <c>crypto.c</c>.</p> + <p> + Own Id: OTP-14639</p> + </item> + <item> + <p> + Documentation added about how to use keys stored in an + Engine.</p> + <p> + Own Id: OTP-14735 Aux Id: OTP-14448 </p> + </item> + <item> + <p> Add engine_ ctrl_cmd_string/3,4 the OpenSSL Engine + support in crypto. </p> + <p> + Own Id: OTP-14801</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>On macOS, <c>crypto</c> would crash if <c>observer</c> + had been started before <c>crypto</c>. On the beta for + macOS 10.13 (High Sierra), <c>crypto</c> would crash. + Both of those bugs have been fixed.</p> + <p> + Own Id: OTP-14499 Aux Id: ERL-251 ERL-439 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Extend crypto:sign, crypto:verify, public_key:sign and + public_key:verify with:</p> + <p> + * support for RSASSA-PS padding for signatures and for + saltlength setting<br/> * X9.31 RSA padding.<br/> * sha, + sha224, sha256, sha384, and sha512 for dss signatures as + mentioned in NIST SP 800-57 Part 1.<br/> * ripemd160 to + be used for rsa signatures.</p> + <p> + This is a manual merge of half of the pull request 838 by + potatosalad from Sept 2015.</p> + <p> + Own Id: OTP-13704 Aux Id: PR838 </p> + </item> + <item> + <p> + A new tuple in <c>crypto:supports/0</c> reports supported + MAC algorithms.</p> + <p> + Own Id: OTP-14504</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + LibreSSL can now be used by the modernized crypto app.</p> + <p> + Own Id: OTP-14247</p> + </item> + <item> + <p> + Add compile option <c>-compile(no_native)</c> in modules + with <c>on_load</c> directive which is not yet supported + by HiPE.</p> + <p> + Own Id: OTP-14316 Aux Id: PR-1390 </p> + </item> + <item> + <p> + Fix a bug in aes cfb128 function introduced by the bug + fix in GitHub pull request <url + href="https://github.com/erlang/otp/pull/1393">#1393</url>.</p> + <p> + Own Id: OTP-14435 Aux Id: PR-1462, PR-1393, OTP-14313 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add basic support for CMAC</p> + <p> + Own Id: OTP-13779 Aux Id: ERL-82 PR-1138 </p> + </item> + <item> + <p> + Removed functions deprecated in crypto-3.0 first released + in OTP-R16B01</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13873</p> + </item> + <item> + <p> + The <c>crypto</c> application now supports OpenSSL 1.1.</p> + <p> + Own Id: OTP-13900</p> + </item> + <item> + <p> + Allow Erlang/OTP to use OpenSSL in FIPS-140 mode, in + order to satisfy specific security requirements (mostly + by different parts of the US federal government). </p> + <p> + See the new crypto users guide "FIPS mode" chapter about + building and using the FIPS support which is disabled by + default.</p> + <p> + (Thanks to dszoboszlay and legoscia)</p> + <p> + Own Id: OTP-13921 Aux Id: PR-1180 </p> + </item> + <item> + <p> + Crypto chacha20-poly1305 as in RFC 7539 enabled for + OpenSSL >= 1.1.</p> + <p> + Thanks to mururu.</p> + <p> + Own Id: OTP-14092 Aux Id: PR-1291 </p> + </item> + <item> + <p> + RSA key generation added to <c>crypto:generate_key/2</c>. + Thanks to wiml.</p> + <p> + An interface is also added to + <c>public_key:generate_key/1</c>.</p> + <p> + Own Id: OTP-14140 Aux Id: ERL-165, PR-1299 </p> + </item> + <item> + <p> + Raised minimum requirement for OpenSSL version to + OpenSSL-0.9.8.c although we recommend a much higher + version, that is a version that is still maintained + officially by the OpenSSL project. Note that using such + an old version may restrict the crypto algorithms + supported.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14171</p> + </item> + <item> + <p> + Deprecate crypto:rand_uniform/2 as it is not + cryptographically strong</p> + <p> + Own Id: OTP-14274</p> + </item> + <item> + <p> + The Crypto application now supports generation of + cryptographically strong random numbers (floats < 1.0 + and integer arbitrary ranges) as a plugin to the 'rand' + module.</p> + <p> + Own Id: OTP-14317 Aux Id: PR-1372 </p> + </item> + <item> + <p> + This replaces the hard coded test values for AES, CMAC + and GCM ciphers with the full validation set from NIST's + CAVP program.</p> + <p> + Own Id: OTP-14436 Aux Id: PR-1396 </p> + </item> + </list> + </section> + +</section> + <section><title>Crypto 3.7.4</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/crypto/doc/src/specs.xml b/lib/crypto/doc/src/specs.xml new file mode 100644 index 0000000000..66c79a906b --- /dev/null +++ b/lib/crypto/doc/src/specs.xml @@ -0,0 +1,4 @@ +<?xml version="1.0" encoding="utf-8" ?> +<specs xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="../specs/specs_crypto.xml"/> +</specs> diff --git a/lib/crypto/doc/src/usersguide.xml b/lib/crypto/doc/src/usersguide.xml index fb088a8285..2dfc966609 100644 --- a/lib/crypto/doc/src/usersguide.xml +++ b/lib/crypto/doc/src/usersguide.xml @@ -4,14 +4,14 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2003</year><year>2016</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>Crypto User's Guide</title> @@ -47,5 +47,8 @@ </p> </description> <xi:include href="licenses.xml"/> + <xi:include href="fips.xml"/> + <xi:include href="engine_load.xml"/> + <xi:include href="engine_keys.xml"/> + <xi:include href="algorithm_details.xml"/> </part> - diff --git a/lib/crypto/doc/src/warning.gif b/lib/crypto/doc/src/warning.gif Binary files differdeleted file mode 100644 index 96af52360e..0000000000 --- a/lib/crypto/doc/src/warning.gif +++ /dev/null |
