diff options
Diffstat (limited to 'lib/crypto/doc/src')
| -rw-r--r-- | lib/crypto/doc/src/Makefile | 29 | ||||
| -rw-r--r-- | lib/crypto/doc/src/algorithm_details.xml | 411 | ||||
| -rw-r--r-- | lib/crypto/doc/src/crypto.xml | 2389 | ||||
| -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/new_api.xml | 329 | ||||
| -rw-r--r-- | lib/crypto/doc/src/note.gif | bin | 1539 -> 0 bytes | |||
| -rw-r--r-- | lib/crypto/doc/src/notes.xml | 738 | ||||
| -rw-r--r-- | lib/crypto/doc/src/specs.xml | 4 | ||||
| -rw-r--r-- | lib/crypto/doc/src/usersguide.xml | 12 | ||||
| -rw-r--r-- | lib/crypto/doc/src/warning.gif | bin | 1498 -> 0 bytes |
14 files changed, 3873 insertions, 573 deletions
diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile index e55242d255..8da494dad6 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,14 @@ 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 new_api.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 +63,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 +80,6 @@ XML_FLAGS += $(HTMLDIR)/%.gif: %.gif $(INSTALL_DATA) $< $@ - docs: pdf html man $(TOP_PDF_FILE): $(XML_FILES) @@ -86,18 +92,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 +122,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..71014764c8 --- /dev/null +++ b/lib/crypto/doc/src/algorithm_details.xml @@ -0,0 +1,411 @@ +<?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> + <p>A <seealso marker="crypto#type-cipher">cipher</seealso> in the + <seealso marker="crypto:new_api#the-new-api">new api</seealso> + is categorized as either + <seealso marker="crypto#type-cipher_no_iv">cipher_no_iv()</seealso>, + <seealso marker="crypto#type-cipher_iv">cipher_iv()</seealso> or + <seealso marker="crypto#type-cipher_aead">cipher_aead()</seealso>. + The letters IV are short for <i>Initialization Vector</i> and + AEAD is an abreviation of <i>Authenticated Encryption with Associated Data</i>. + </p> + <p>Due to irregular naming conventions, some cipher names in the old api are + substitued by new names in the new api. For a list of retired names, see + <seealso marker="crypto:new_api#retired-cipher-names">Retired cipher names</seealso>. + </p> + <p>To dynamically check availability, check that the name in the <i>Cipher and Mode</i> column is present in the + list returned by <seealso marker="crypto#supports-1">crypto:supports(ciphers)</seealso>. + </p> + + <section> + <title>Ciphers without an IV - cipher_no_iv()</title> + <p>To be used with: + </p> + <list> + <item><seealso marker="crypto#crypto_one_time/4">crypto_one_time/4</seealso></item> + <item><seealso marker="crypto#crypto_init/3">crypto_init/3</seealso></item> + </list> + <p>The ciphers are: + </p> + <table> + <row> + <cell><strong>Cipher and Mode</strong></cell> + <cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell> + <cell><strong>Block size</strong><br/><strong>[bytes]</strong></cell> + </row> + <row><cell><c>aes_128_ecb</c></cell> <cell>16</cell> <cell>16</cell></row> + <row><cell><c>aes_192_ecb</c></cell> <cell>24</cell> <cell>16</cell></row> + <row><cell><c>aes_256_ecb</c></cell> <cell>32</cell> <cell>16</cell></row> + <row><cell><c>blowfish_ecb</c></cell> <cell>16</cell> <cell> 8</cell></row> + <row><cell><c>des_ecb</c></cell> <cell> 8</cell> <cell> 8</cell></row> + <row><cell><c>rc4</c></cell> <cell>16</cell> <cell> 1</cell></row> + <tcaption>Ciphers without IV</tcaption> + </table> + </section> + + <section> + <title>Ciphers with an IV - cipher_iv()</title> + <p>To be used with: + </p> + <list> + <item><seealso marker="crypto#crypto_one_time/5">crypto_one_time/5</seealso></item> + <item><seealso marker="crypto#crypto_init/4">crypto_init/4</seealso></item> + <item><seealso marker="crypto#crypto_dyn_iv_init/3">crypto_dyn_iv_init/3</seealso></item> + </list> + <p>The ciphers are: + </p> + <table> + <row> + <cell><strong>Cipher and Mode</strong></cell> + <cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell> + <cell><strong>IV length</strong><br/><strong>[bytes]</strong></cell> + <cell><strong>Block size</strong><br/><strong>[bytes]</strong></cell> + <cell><strong>Limited to</strong><br/><strong>OpenSSL versions</strong></cell> + </row> + <row><cell><c>aes_128_cbc</c></cell> <cell>16</cell> <cell>16</cell> <cell>16</cell> <cell></cell></row> + <row><cell><c>aes_192_cbc</c></cell> <cell>24</cell> <cell>16</cell> <cell>16</cell> <cell></cell></row> + <row><cell><c>aes_256_cbc</c></cell> <cell>32</cell> <cell>16</cell> <cell>16</cell> <cell></cell></row> + <row><cell><c>aes_128_cfb8</c></cell> <cell>16</cell> <cell>16</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>aes_192_cfb8</c></cell> <cell>24</cell> <cell>16</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>aes_256_cfb8</c></cell> <cell>32</cell> <cell>16</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>aes_128_cfb128</c></cell><cell>16</cell> <cell>16</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>aes_192_cfb128</c></cell><cell>24</cell> <cell>16</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>aes_256_cfb128</c></cell><cell>32</cell> <cell>16</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>aes_128_ctr</c></cell> <cell>16</cell> <cell>16</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>aes_192_ctr</c></cell> <cell>24</cell> <cell>16</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>aes_256_ctr</c></cell> <cell>32</cell> <cell>16</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>aes_ige256</c></cell> <cell>16</cell> <cell>32</cell> <cell>16</cell> <cell></cell></row> + <row><cell><c>blowfish_cbc</c></cell> <cell>16</cell> <cell> 8</cell> <cell> 8</cell> <cell></cell></row> + <row><cell><c>blowfish_cfb64</c></cell><cell>16</cell> <cell> 8</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>blowfish_ofb64</c></cell><cell>16</cell> <cell> 8</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>chacha20</c></cell> <cell>32</cell> <cell>16</cell> <cell> 1</cell> <cell>≥1.1.0d</cell></row> + <row><cell><c>des_cbc</c></cell> <cell> 8</cell> <cell> 8</cell> <cell> 8</cell> <cell></cell></row> + <row><cell><c>des_ede3_cbc</c></cell> <cell>24</cell> <cell> 8</cell> <cell> 8</cell> <cell></cell></row> + <row><cell><c>des_cfb</c></cell> <cell> 8</cell> <cell> 8</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>des_ede3_cfb</c></cell> <cell>24</cell> <cell> 8</cell> <cell> 1</cell> <cell></cell></row> + <row><cell><c>rc2_cbc</c></cell> <cell>16</cell> <cell> 8</cell> <cell> 8</cell> <cell></cell></row> + <tcaption>Ciphers with IV</tcaption> + </table> + </section> + + <section> + <title>Ciphers with AEAD - cipher_aead()</title> + <p>To be used with: + </p> + <list> + <item><seealso marker="crypto#crypto_one_time_aead/6">crypto_one_time_aead/6</seealso></item> + <item><seealso marker="crypto#crypto_one_time_aead/7">crypto_one_time_aead/7</seealso></item> + </list> + <p>The ciphers are: + </p> + <table> + <row> + <cell><strong>Cipher and Mode</strong></cell> + <cell><strong>Key length</strong><br/><strong>[bytes]</strong></cell> + <cell><strong>IV length</strong><br/><strong>[bytes]</strong></cell> + <cell><strong>AAD length</strong><br/><strong>[bytes]</strong></cell> + <cell><strong>Tag length</strong><br/><strong>[bytes]</strong></cell> + <cell><strong>Block size</strong><br/><strong>[bytes]</strong></cell> + <cell><strong>Limited to</strong><br/><strong>OpenSSL versions</strong></cell> + </row> + <row><cell><c>aes_128_ccm</c></cell> <cell>16</cell> <cell>7-13</cell> <cell>any</cell> <cell>even 4-16<br/>default: 12</cell> <cell>any</cell><cell>≥1.0.1</cell></row> + <row><cell><c>aes_192_ccm</c></cell> <cell>24</cell> <cell>7-13</cell> <cell>any</cell> <cell>even 4-16<br/>default: 12</cell> <cell>any</cell><cell>≥1.0.1</cell></row> + <row><cell><c>aes_256_ccm</c></cell> <cell>32</cell> <cell>7-13</cell> <cell>any</cell> <cell>even 4-16<br/>default: 12</cell> <cell>any</cell><cell>≥1.0.1</cell></row> + + <row><cell><c>aes_128_gcm</c></cell> <cell>16</cell> <cell>≥1</cell> <cell>any</cell> <cell>1-16<br/>default: 16</cell> <cell>any</cell><cell>≥1.0.1</cell></row> + <row><cell><c>aes_192_gcm</c></cell> <cell>24</cell> <cell>≥1</cell> <cell>any</cell> <cell>1-16<br/>default: 16</cell> <cell>any</cell><cell>≥1.0.1</cell></row> + <row><cell><c>aes_256_gcm</c></cell> <cell>32</cell> <cell>≥1</cell> <cell>any</cell> <cell>1-16<br/>default: 16</cell> <cell>any</cell><cell>≥1.0.1</cell></row> + + <row><cell><c>chacha20_poly1305</c></cell><cell>32</cell> <cell>1-16</cell> <cell>any</cell> <cell>16</cell> <cell>any</cell><cell>≥1.1.0</cell></row> + <tcaption>AEAD ciphers</tcaption> + </table> + </section> + </section> + + + <section> + <title>Message Authentication Codes (MACs)</title> + <p>To be used in <seealso marker="crypto#mac-4">mac/4</seealso> and + <seealso marker="crypto:new_api#macs--message-authentication-codes-">related functions</seealso>. + </p> + + <section> + <title>CMAC</title> + <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 returned by <seealso marker="crypto#supports-1">crypto:supports(macs)</seealso>. + Also check that the name in the <i>Cipher and Mode</i> column is present in the + list returned by <seealso marker="crypto#supports-1">crypto:supports(ciphers)</seealso>. + </p> + <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>(= default length)</strong><br/><strong>[bytes]</strong></cell> + </row> + <row><cell><c>aes_128_cbc</c></cell> <cell>16</cell> <cell>16</cell></row> + <row><cell><c>aes_192_cbc</c></cell> <cell>24</cell> <cell>16</cell></row> + <row><cell><c>aes_256_cbc</c></cell> <cell>32</cell> <cell>16</cell></row> + <row><cell><c>aes_128_ecb</c></cell> <cell>16</cell> <cell>16</cell></row> + <row><cell><c>aes_192_ecb</c></cell> <cell>24</cell> <cell>16</cell></row> + <row><cell><c>aes_256_ecb</c></cell> <cell>32</cell> <cell>16</cell></row> + <row><cell><c>blowfish_cbc</c></cell> <cell>16</cell> <cell> 8</cell></row> + <row><cell><c>blowfish_ecb</c></cell> <cell>16</cell> <cell> 8</cell></row> + <row><cell><c>des_cbc</c></cell> <cell> 8</cell> <cell> 8</cell></row> + <row><cell><c>des_ecb</c></cell> <cell> 8</cell> <cell> 8</cell></row> + <row><cell><c>des_ede3_cbc</c></cell> <cell>24</cell> <cell> 8</cell></row> + <row><cell><c>rc2_cbc</c></cell> <cell>16</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 returned by <seealso marker="crypto#supports-1">crypto:supports(macs)</seealso> and + that the hash name is present in the + list returned by <seealso marker="crypto#supports-1">crypto:supports(hashs)</seealso>. + </p> + + <table> + <row> + <cell><strong>Hash</strong></cell> + <cell><strong>Max Mac Length</strong><br/><strong>(= default length)</strong><br/><strong>[bytes]</strong></cell> + </row> + <row><cell><c>sha</c></cell> <cell>20</cell></row> + <row><cell><c>sha224</c></cell> <cell>28</cell></row> + <row><cell><c>sha256</c></cell> <cell>32</cell></row> + <row><cell><c>sha384</c></cell> <cell>48</cell></row> + <row><cell><c>sha512</c></cell> <cell>64</cell></row> + <row><cell><c>sha3_224</c></cell> <cell>28</cell></row> + <row><cell><c>sha3_256</c></cell> <cell>32</cell></row> + <row><cell><c>sha3_384</c></cell> <cell>48</cell></row> + <row><cell><c>sha3_512</c></cell> <cell>64</cell></row> + <row><cell><c>blake2b</c></cell> <cell>64</cell></row> + <row><cell><c>blake2s</c></cell> <cell>32</cell></row> + <row><cell><c>md4</c></cell> <cell>16</cell></row> + <row><cell><c>md5</c></cell> <cell>16</cell></row> + <row><cell><c>ripemd160</c></cell> <cell>20</cell></row> + <tcaption>HMAC output sizes</tcaption> + </table> + + + </section> + + <section> + <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 returned by <seealso marker="crypto#supports-1">crypto:supports(macs)</seealso>. + </p> + <p>The poly1305 mac wants an 32 bytes key and produces a 16 byte MAC by default. + </p> + </section> + + </section> + + <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 returned by <seealso marker="crypto#supports-1">crypto:supports(hashs)</seealso>. + </p> + + <table> + <row><cell><strong>Type</strong></cell> + <cell><strong>Names</strong></cell> + <cell><strong>Limitated to</strong><br/><strong>OpenSSL versions</strong></cell> + </row> + <row><cell>SHA1</cell><cell>sha</cell><cell></cell></row> + <row><cell>SHA2</cell><cell>sha224, sha256, sha384, sha512</cell><cell></cell></row> + <row><cell>SHA3</cell><cell>sha3_224, sha3_256, sha3_384, sha3_512</cell><cell>≥1.1.1</cell></row> + <row><cell>MD4</cell><cell>md4</cell><cell></cell></row> + <row><cell>MD5</cell><cell>md5</cell><cell></cell></row> + <row><cell>RIPEMD</cell><cell>ripemd160</cell><cell></cell></row> + <tcaption></tcaption> + </table> + </section> + + <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 returned by <seealso marker="crypto#supports-1">crypto:supports(public_keys)</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 returned by <seealso marker="crypto#supports-1">crypto:supports(public_keys)</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 returned by <seealso marker="crypto#supports-1">crypto:supports(public_keys)</seealso>. + If the atom <c>ec_gf2m</c> also is present, the characteristic two field curves are available. + </p> + <p>The actual supported named curves could be checked by examining the + list returned by <seealso marker="crypto#supports-1">crypto:supports(curves)</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 returned by <seealso marker="crypto#supports-1">crypto:supports(public_keys)</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 + list returned by <seealso marker="crypto#supports-1">crypto:supports(curves)</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 returned by <seealso marker="crypto#supports-1">crypto:supports(public_keys)</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 returned by <seealso marker="crypto#supports-1">crypto:supports(public_keys)</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 returned by <seealso marker="crypto#supports-1">crypto:supports(curves)</seealso>. + </p> + </section> + + </section> + + +</chapter> + + + + + diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 82e450ec21..3973cf3f9f 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -1,17 +1,16 @@ -<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <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,242 +18,974 @@ 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>BLAKE2</tag> + <item> + <url href="https://blake2.net/">BLAKE2 — fast secure hashing</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, new API</datatype_title> + <datatype> + <name name="cipher"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="cipher_no_iv"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="cipher_iv"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="cipher_aead"/> + <desc> + <p>Ciphers known by the CRYPTO application when using the + <seealso marker="crypto:new_api#the-new-api">new API</seealso>.</p> + <p>Note that this list might be reduced if the underlying libcrypto does not support all of them.</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_title>Ciphers, old API</datatype_title> + <datatype> + <name name="block_cipher_with_iv"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="block_cipher_without_iv"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="stream_cipher"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="aead_cipher"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="cbc_cipher"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="cfb_cipher"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="ctr_cipher"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="ecb_cipher"/> + <desc> + <p>Ciphers known by the CRYPTO application when using the + <seealso marker="crypto:new_api#the-old-api">old API</seealso>.</p> + <p>Note that this list might be reduced if the underlying libcrypto does not support all of them.</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="retired_cbc_cipher_aliases"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="retired_cfb_cipher_aliases"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="retired_ctr_cipher_aliases"/> + <desc> + </desc> + </datatype> + <datatype> + <name name="retired_ecb_cipher_aliases"/> + <desc> + <p>Alternative, old names of ciphers known by the CRYPTO application when using the + <seealso marker="crypto:new_api#the-old-api">old API</seealso>. + See <seealso marker="crypto:new_api#retired-cipher-names">Retired cipher names</seealso> for names to + use instead to be prepared for an easy convertion to the + <seealso marker="crypto:new_api#the-new-api">new API</seealso>. + </p> + <p>Note that this list might be reduced if the underlying libcrypto does not support all of them.</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_title>Digests and hash</datatype_title> + <datatype> + <name name="hash_algorithm"/> + <desc> + </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> + <name name="hmac_hash_algorithm"/> + <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="cmac_cipher_algorithm"/> + <desc> + </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> + + <datatype> + <name name="ecdsa_digest_type"/> + <desc> + </desc> + </datatype> - <code>dh_public() = key_value() </code> + <datatype> + <name name="sha1"/> + <name name="sha2"/> + <name name="sha3"/> + <name name="blake2"/> + <desc> + </desc> + </datatype> - <code>dh_private() = key_value() </code> + <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>dh_params() = [key_value()] = [P, G] | [P, G, PrivateKeyBitLength]</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>ecdh_public() = key_value() </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_private() = 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_params() = ec_named_curve() | ec_explicit_curve()</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>ec_explicit_curve() = - {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(), CoFactor :: none | integer()} </code> + <datatype> + <name name="key_integer"/> + <desc> + <p>Always <c>binary()</c> when used as return value</p> + </desc> + </datatype> - <code>ec_field() = {prime_field, Prime :: integer()} | - {characteristic_two_field, M :: integer(), Basis :: ec_basis()}</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_basis() = {tpbasis, K :: non_neg_integer()} | - {ppbasis, K1 :: non_neg_integer(), K2 :: non_neg_integer(), K3 :: non_neg_integer()} | - onbasis</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_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> + <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> + + <datatype> + <name name="ecdsa_public"/> + <name name="ecdsa_private"/> + <name name="ecdsa_params"/> + <desc> + </desc> + </datatype> + + <datatype> + <name name="eddsa_public"/> + <name name="eddsa_private"/> + <name name="eddsa_params"/> + <desc> + </desc> + </datatype> + + <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> + + <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> + + <datatype_title>Public Key Ciphers</datatype_title> + + <datatype> + <name name="pk_encrypt_decrypt_algs"/> + <desc> + <p>Algorithms for public key encrypt/decrypt. Only RSA is supported.</p> + </desc> + </datatype> + + <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> + + <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> + + <datatype_title>Public Key Sign and Verify</datatype_title> + + <datatype> + <name name="pk_sign_verify_algs"/> + <desc> + <p>Algorithms for sign and verify.</p> + </desc> + </datatype> + + <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>stream_cipher() = rc4 | aes_ctr </code> + <datatype> + <name name="dh_params"/> + <desc> + <code>dh_params() = [P, G] | [P, G, PrivateKeyBitLength]</code> + </desc> + </datatype> + + <datatype> + <name name="ecdh_public"/> + <name name="ecdh_private"/> + <name name="ecdh_params"/> + <desc> + </desc> + </datatype> + + <datatype_title>Types for Engines</datatype_title> - <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="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> - <code>aead_cipher() = aes_gcm | chacha20_poly1305 </code> + <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> - <code>stream_key() = aes_key() | rc4_key() </code> + <datatype> + <name name="password"/> + <desc> + <p>The password of the key stored in an engine. + </p> + </desc> + </datatype> - <code>block_key() = aes_key() | blowfish_key() | des_key()| des3_key() </code> + <datatype> + <name name="engine_method_type"/> + </datatype> - <code>aes_key() = iodata() </code> <p>Key length is 128, 192 or 256 bits</p> + <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> - <code>rc4_key() = iodata() </code> <p>Variable key length from 8 bits up to 2048 bits (usually between 40 and 256)</p> + <datatype_title>Internal data types</datatype_title> - <code>blowfish_key() = iodata() </code> <p>Variable key length from 32 bits up to 448 bits</p> + <datatype> + <name name="crypto_state"/> + <name name="hash_state"/> + <name name="hmac_state"/> + <name name="mac_state"/> + <name name="stream_state"/> + <desc> + <p>Contexts with an internal state that should not be manipulated but passed between function calls. + </p> + </desc> + </datatype> - <code>des_key() = iodata() </code> <p>Key length is 64 bits (in CBC mode only 8 bits are used)</p> + <datatype_title>Error types</datatype_title> - <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="run_time_error"/> + <desc> + <p>The exception <c>error:badarg</c> signifies that one or more arguments are of wrong data type, + or are otherwise badly formed. + </p> + <p>The exception <c>error:notsup</c> signifies that the algorithm is known but is not supported + by current underlying libcrypto or explicitly disabled when building that. + </p> + <p>For a list of supported algorithms, see <seealso marker="#supports-0">supports/0</seealso>. + </p> + </desc> + </datatype> - <code>digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512</code> + <datatype> + <name name="descriptive_error"/> + <desc> + <p>This is a more developed variant of the older + <seealso marker="#type-run_time_error">run_time_error()</seealso>. + </p> + <p>The exception is:</p> + <pre> + {Tag, {C_FileName,LineNumber}, Description} + + Tag = badarg | notsup | error + C_FileName = string() + LineNumber = integer() + Description = string() + </pre> + + <p>It is like the older type an exception of the <c>error</c> class. In addition they contain + a descriptive text in English. That text is targeted to a developer. Examples are "Bad key size" + or "Cipher id is not an atom". + </p> + <p>The exception tags are:</p> + <taglist> + <tag><c>badarg</c></tag> + <item><p>Signifies that one or more arguments are of wrong data type or are otherwise badly formed.</p> + </item> + + <tag><c>notsup</c></tag> + <item><p>Signifies that the algorithm is known but is not supported by current underlying libcrypto + or explicitly disabled when building that one.</p> + </item> + + <tag><c>error</c></tag> + <item><p>An error condition that should not occur, for example a memory allocation failed or + the underlying cryptolib returned an error code, for example "Can't initialize context, step 1". + Thoose text usually needs searching the C-code to be understood.</p> + </item> + </taglist> + <p>To catch the exception, use for example:</p> + <code> + try crypto:crypto_init(Ciph, Key, IV, true) + catch + error:{Tag, {C_FileName,LineNumber}, Description} -> + do_something(......) + ..... + end + </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> + </datatypes> - </section> + <!--================ FUNCTIONS ================--> + <section> + <title>New API</title> + </section> <funcs> <func> - <name>block_encrypt(Type, Key, PlainText) -> CipherText</name> - <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> + <name name="crypto_init" arity="3" since="OTP 22.0"/> + <fsummary>Initializes a series of encryptions or decryptions</fsummary> <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>As <seealso marker="#crypto_init/4">crypto_init/4</seealso> but for ciphers without IVs.</p> </desc> </func> <func> - <name>block_decrypt(Type, Key, CipherText) -> PlainText</name> - <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> + <name name="crypto_init" arity="4" since="OTP 22.0"/> + <fsummary>Initializes a series of encryptions or decryptions</fsummary> <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>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>. + Initializes a series of encryptions or decryptions and creates an internal state + with a reference that is returned. + The actual encryption or decryption is done by + <seealso marker="crypto#crypto_update/2">crypto_update/2</seealso>. + </p> + <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>. For decryption, set it to <c>false</c>. + </p> + <p>See <seealso marker="crypto:new_api#examples-of-crypto_init-4-and-crypto_update-2"> + examples in the 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> - <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>AAD = IVec = CipherText = CipherTag = binary()</v> - <v>TagLength = 1..16</v> - </type> + <name name="crypto_update" arity="2" since="OTP 22.0"/> + <fsummary>Do an actual crypto operation on a part of the full text</fsummary> <desc> - <p>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher. - <c>IVec</c> is an arbitrary initializing vector.</p> - <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>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>. + It does an actual crypto operation on a part of the full text. If the part is less + than a number of full blocks, only the full blocks (possibly none) are encrypted + or decrypted and the remaining bytes are saved to the next <c>crypto_update</c> operation. + The <c>State</c> should be created with + <seealso marker="crypto#crypto_init/3">crypto_init/3</seealso> + or + <seealso marker="crypto#crypto_init/4">crypto_init/4</seealso>. + </p> + <p>See <seealso marker="crypto:new_api#examples-of-crypto_init-4-and-crypto_update-2"> + examples in the User's Guide.</seealso> + </p> </desc> </func> <func> - <name>block_decrypt(Type, Key, Ivec, CipherText) -> PlainText</name> - <name>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>AAD = IVec = CipherText = CipherTag = binary()</v> - </type> + <name name="crypto_dyn_iv_init" arity="3" since="OTP 22.0"/> + <fsummary>Initializes a series of encryptions or decryptions where the IV is provided later</fsummary> <desc> - <p>Decrypt <c>CipherText</c> according to <c>Type</c> block cipher. - <c>IVec</c> is an arbitrary initializing vector.</p> - <p>In AEAD (Authenticated Encryption with Associated Data) mode, decrypt - <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>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>. + Initializes a series of encryptions or decryptions where the IV is provided later. + The actual encryption or decryption is done by + <seealso marker="crypto#crypto_dyn_iv_update/3">crypto_dyn_iv_update/3</seealso>. + </p> + <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>. For decryption, set it to <c>false</c>. + </p> </desc> </func> - - <func> - <name>bytes_to_integer(Bin) -> Integer </name> + + <func> + <name name="crypto_dyn_iv_update" arity="3" since="OTP 22.0"/> + <fsummary>Do an actual crypto operation on a part of the full text and the IV is supplied for each part</fsummary> + <desc> + <p>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>. + Do an actual crypto operation on a part of the full text and the IV is supplied for each part. + The <c>State</c> should be created with + <seealso marker="crypto#crypto_dyn_iv_init/3">crypto_dyn_iv_init/3</seealso>. + </p> + </desc> + </func> + + <func> + <name name="crypto_one_time" arity="4" since="OTP 22.0"/> + <fsummary>Do a complete encrypt or decrypt of the full text</fsummary> + <desc> + <p>As <seealso marker="#crypto_one_time/5">crypto_one_time/5</seealso> but for ciphers without IVs.</p> + </desc> + </func> + + <func> + <name name="crypto_one_time" arity="5" since="OTP 22.0"/> + <fsummary>Do a complete encrypt or decrypt of the full text</fsummary> + <desc> + <p>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>. + Do a complete encrypt or decrypt of the full text in the argument <c>Data</c>. + </p> + <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>. For decryption, set it to <c>false</c>. + </p> + <p>See <seealso marker="crypto:new_api#example-of-crypto_one_time-5">examples in the User's Guide.</seealso> + </p> + </desc> + </func> + + <func> + <name name="crypto_one_time_aead" arity="6" since="OTP 22.0"/> + <name name="crypto_one_time_aead" arity="7" since="OTP 22.0"/> + <fsummary>Do a complete encrypt or decrypt with an AEAD cipher of the full text</fsummary> + <desc> + <p>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>. + Do a complete encrypt or decrypt with an AEAD cipher of the full text. + </p> + <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c> and set the <c>TagOrTagLength</c> + to the wanted size of the tag, that is, the tag length. If the default length is wanted, the + <c>crypto_aead/6</c> form may be used. + </p> + <p>For decryption, set the <c>EncryptFlag</c> to <c>false</c> and put the tag to be checked + in the argument <c>TagOrTagLength</c>. + </p> + <p>See <seealso marker="crypto:new_api#example-of-crypto_one_time_aead-6">examples in the User's Guide.</seealso> + </p> + </desc> + </func> + + <func> + <name name="supports" arity="1" since="OTP 22.0"/> + <fsummary>Provide a list of available crypto algorithms.</fsummary> + <desc> + <p> Can be used to determine which crypto algorithms that are supported + by the underlying libcrypto library</p> + <p>See <seealso marker="#hash_info-1">hash_info/1</seealso> and <seealso marker="#cipher_info-1">cipher_info/1</seealso> + for information about the hash and cipher algorithms. + </p> + </desc> + </func> + + <func> + <name name="mac" arity="3" since="OTP @OTP-13872@"/> + <fsummary></fsummary> + <desc> + <p>Short for <seealso marker="#mac-4">mac(Type, undefined, Key, Data)</seealso>. + </p> + </desc> + </func> + + <func> + <name name="mac" arity="4" since="OTP @OTP-13872@"/> + <fsummary></fsummary> + <desc> + <p>Computes a MAC (Message Authentication Code) of type <c>Type</c> from <c>Data</c>. + </p> + + <p><c>SubType</c> depends on the MAC <c>Type</c>: + </p> + <list> + <item>For <c>hmac</c> it is a hash algorithm, see + <seealso marker="algorithm_details#hmac">Algorithm Details</seealso> in the User's Guide. + </item> + <item>For <c>cmac</c> it is a cipher suitable for cmac, see + <seealso marker="algorithm_details#cmac">Algorithm Details</seealso> in the User's Guide. + </item> + <item>For <c>poly1305</c> it should be set to <c>undefined</c> or the + <seealso marker="#mac_init-2">mac/2</seealso> function could be used instead, see + <seealso marker="algorithm_details#poly1305">Algorithm Details</seealso> in the User's Guide. + </item> + </list> + + <p><c>Key</c> is the authentication key with a length according to the + <c>Type</c> and <c>SubType</c>. + The key length could be found with the + <seealso marker="#hash_info-1">hash_info/1</seealso> (<c>hmac</c>) for and + <seealso marker="#cipher_info-1">cipher_info/1</seealso> (<c>cmac</c>) + functions. For <c>poly1305</c> the key length is 32 bytes. Note that + the cryptographic quality of the key is not checked. + </p> + + <p>The <c>Mac</c> result will have a default length depending on the <c>Type</c> and <c>SubType</c>. + To set a shorter length, use <seealso marker="#macN-4">macN/4</seealso> or + <seealso marker="#macN-5">macN/5</seealso> instead. + The default length is documented in + <seealso marker="algorithm_details#message-authentication-codes--macs-">Algorithm Details</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="macN" arity="4" since="OTP @OTP-13872@"/> + <fsummary></fsummary> + <desc> + <p>Short for <seealso marker="#macN-5">macN(Type, undefined, Key, Data, MacLength)</seealso>. + </p> + </desc> + </func> + + <func> + <name name="macN" arity="5" since="OTP @OTP-13872@"/> + <fsummary></fsummary> + <desc> + <p>Computes a MAC (Message Authentication Code) + as <seealso marker="#mac-3">mac/3</seealso> and <seealso marker="#mac-4">mac/4</seealso> but + <c>MacLength</c> will limit the size of the resultant <c>Mac</c> to + at most <c>MacLength</c> bytes. + Note that if <c>MacLength</c> is greater than the actual number of + bytes returned from the underlying hash, the returned hash will have + that shorter length instead. + </p> + <p>The max <c>MacLength</c> is documented in + <seealso marker="algorithm_details#message-authentication-codes--macs-">Algorithm Details</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="mac_init" arity="2" since="OTP @OTP-13872@"/> + <fsummary></fsummary> + <desc> + <p>Short for <seealso marker="#mac_init-3">mac_init(Type, undefined, Key)</seealso>. + </p> + </desc> + </func> + + <func> + <name name="mac_init" arity="3" since="OTP @OTP-13872@"/> + <fsummary></fsummary> + <desc> + <p>Initializes the context for streaming MAC operations. + </p> + <p><c>Type</c> determines which mac algorithm to use in the MAC operation. + </p> + + <p><c>SubType</c> depends on the MAC <c>Type</c>: + </p> + <list> + <item>For <c>hmac</c> it is a hash algorithm, see + <seealso marker="algorithm_details#hmac">Algorithm Details</seealso> in the User's Guide. + </item> + <item>For <c>cmac</c> it is a cipher suitable for cmac, see + <seealso marker="algorithm_details#cmac">Algorithm Details</seealso> in the User's Guide. + </item> + <item>For <c>poly1305</c> it should be set to <c>undefined</c> or the + <seealso marker="#mac_init-2">mac/2</seealso> function could be used instead, see + <seealso marker="algorithm_details#poly1305">Algorithm Details</seealso> in the User's Guide. + </item> + </list> + + <p><c>Key</c> is the authentication key with a length according to the + <c>Type</c> and <c>SubType</c>. + The key length could be found with the + <seealso marker="#hash_info-1">hash_info/1</seealso> (<c>hmac</c>) for and + <seealso marker="#cipher_info-1">cipher_info/1</seealso> (<c>cmac</c>) + functions. For <c>poly1305</c> the key length is 32 bytes. Note that + the cryptographic quality of the key is not checked. + </p> + + <p>The returned <c>State</c> should be used in one or more subsequent calls to + <seealso marker="#mac_update-2">mac_update/2</seealso>. + The MAC value is finally returned by calling + <seealso marker="#mac_final-1">mac_final/1</seealso> or + <seealso marker="#mac_finalN-2">mac_finalN/2</seealso>. + </p> + + <p>See <seealso marker="crypto:new_api#example-of-mac_init-mac_update-and-mac_final"> + examples in the User's Guide.</seealso> + </p> + </desc> + </func> + + <func> + <name name="mac_update" arity="2" since="OTP @OTP-13872@"/> + <fsummary></fsummary> + <desc> + <p>Updates the MAC represented by <c>State0</c> using the given <c>Data</c> which + could be of any length. + </p> + <p>The <c>State0</c> is the State value originally from a MAC init function, that is + <seealso marker="#mac_init-2">mac_init/2</seealso>, + <seealso marker="#mac_init-3">mac_init/3</seealso> or + a previous call of <c>mac_update/2</c>. + The value <c>State0</c> is returned unchanged by the function as <c>State</c>. + </p> + </desc> + </func> + + <func> + <name name="mac_final" arity="1" since="OTP @OTP-13872@"/> + <fsummary></fsummary> + <desc> + <p>Finalizes the MAC operation referenced by <c>State</c>. The <c>Mac</c> result will have + a default length depending on the <c>Type</c> and <c>SubType</c> in the + <seealso marker="#mac_init-3">mac_init/2,3</seealso> call. + To set a shorter length, use <seealso marker="#mac_finalN-2">mac_finalN/2</seealso> instead. + The default length is documented in + <seealso marker="algorithm_details#message-authentication-codes--macs-">Algorithm Details</seealso> + in the User's Guide. + </p> + </desc> + </func> + + <func> + <name name="mac_finalN" arity="2" since="OTP @OTP-13872@"/> + <fsummary></fsummary> + <desc> + <p>Finalizes the MAC operation referenced by <c>State</c>. + </p> + <p><c>Mac</c> will be a binary with at most <c>MacLength</c> bytes. + Note that if <c>MacLength</c> is greater than the actual number of + bytes returned from the underlying hash, the returned hash will have + that shorter length instead. + </p> + <p>The max <c>MacLength</c> is documented in + <seealso marker="algorithm_details#message-authentication-codes--macs-">Algorithm Details</seealso> + in the User's Guide. + </p> + </desc> + </func> + </funcs> + + <section> + <title>API kept from previous versions</title> + </section> + + <funcs> + <func> + <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 +993,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 +1003,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 +1066,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,94 +1079,46 @@ </func> <func> - <name>hmac(Type, Key, Data) -> Mac</name> - <name>hmac(Type, Key, Data, MacLength) -> Mac</name> - <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> - will limit the size of the resultant <c>Mac</c>.</p> - </desc> - </func> - - <func> - <name>hmac_init(Type, Key) -> Context</name> - <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 - key. The key can be any length.</p> - </desc> - </func> - - <func> - <name>hmac_update(Context, Data) -> NewContext</name> - <fsummary></fsummary> - <type> - <v>Context = NewContext = binary()</v> - <v>Data = iodata()</v> - </type> + <name name="info_fips" arity="0" since="OTP 20.0"/> + <fsummary>Provides information about the FIPS operating status.</fsummary> <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 - <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 - <seealso marker="#hmac_final_n-2">hmac_final_n</seealso> + <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> - <warning><p>Do not use a <c>Context</c> as argument in more than one - 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> - </desc> - </func> - - <func> - <name>hmac_final(Context) -> Mac</name> - <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> + <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>hmac_final_n(Context, HashLen) -> Mac</name> - <fsummary></fsummary> - <type> - <v>Context = Mac = binary()</v> - <v>HashLen = non_neg_integer()</v> - </type> + <name name="enable_fips_mode" arity="1" since="OTP 21.1"/> + <fsummary>Change FIPS mode.</fsummary> <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> + <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>info_lib() -> [{Name,VerNum,VerStr}]</name> + <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 +1126,74 @@ 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="hash_info" arity="1" since="OTP 22.0"/> + <fsummary>Information about supported hash algorithms.</fsummary> + <desc> + <p>Provides a map with information about block_size, size and possibly other properties of the + hash algorithm in question. + </p> + <p>For a list of supported hash algorithms, see <seealso marker="#supports-0">supports/0</seealso>. + </p> + </desc> + </func> + + <func> + <name name="cipher_info" arity="1" since="OTP 22.0"/> + <fsummary>Information about supported ciphers.</fsummary> + <desc> + <p>Provides a map with information about block_size, key_length, iv_length and possibly other properties of the + cipher algorithm in question. + </p> + <note> + <p>The ciphers <c>aes_cbc</c>, <c>aes_cfb8</c>, <c>aes_cfb128</c>, <c>aes_ctr</c>, + <c>aes_ecb</c>, <c>aes_gcm</c> and <c>aes_ccm</c> + has no keylength in the <c>Type</c> as opposed to for example <c>aes_128_ctr</c>. They adapt to the length of + the key provided in the encrypt and decrypt function. Therefor it is impossible to return a valid keylength + in the map.</p> + <p>Always use a <c>Type</c> with an explicit key length, + </p> + </note> + <p>For a list of supported cipher algorithms, see <seealso marker="#supports-0">supports/0</seealso>. + </p> + </desc> + </func> + + <func> + <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>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 +1204,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 +1217,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 +1233,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 +1245,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,19 +1271,311 @@ </func> <func> - <name>sign(Algorithm, DigestType, Msg, Key) -> binary()</name> - <fsummary> Create digital signature.</fsummary> + <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 name="stop" arity="0" since=""/> + <fsummary> Equivalent to application:stop(crypto).</fsummary> + <desc> + <p> Equivalent to application:stop(crypto).</p> + </desc> + </func> + + <func> + <name name="strong_rand_bytes" arity="1" since="OTP R14B03"/> + <fsummary>Generate a binary of random bytes</fsummary> + <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 raise exception <c>error:low_entropy</c> in case the random generator + failed due to lack of secure "randomness".</p> + </desc> + </func> + + <func> + <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 cannot 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>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> + <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, + 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_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><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-22.0">rand_seed_alg(Alg, Seed) -> rand:state()</name> + <fsummary>Strong random number generation plugin state</fsummary> + <type> + <v>Alg = crypto_aes</v> </type> <desc> + <marker id="rand_seed_alg-2" /> + <p> + Creates a state object for + <seealso marker="stdlib:rand">random number generation</seealso>, + in order to generate cryptographically unpredictable random numbers, + and saves it in the process dictionary before returning it as well. + See also + <seealso marker="#rand_seed_alg_s-2">rand_seed_alg_s/2</seealso>. + </p> + <p><em>Example</em></p> + <pre> +_ = crypto:rand_seed_alg(crypto_aes, "my seed"), +IntegerValue = rand:uniform(42), % [1; 42] +FloatValue = rand:uniform(), % [0.0; 1.0[ +_ = crypto:rand_seed_alg(crypto_aes, "my seed"), +IntegerValue = rand:uniform(42), % Same values +FloatValue = rand:uniform(). % again + </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> + <p> + When using the state object from this function the + <seealso marker="stdlib:rand">rand</seealso> functions using it + may throw exception <c>low_entropy</c> in case the random generator + failed due to lack of secure "randomness". + </p> + <note> + <p> + The state returned from this function cannot 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 since="OTP 22.0">rand_seed_alg_s(Alg, Seed) -> rand:state()</name> + <fsummary>Strong random number generation plugin state</fsummary> + <type> + <v>Alg = crypto_aes</v> + </type> + <desc> + <marker id="rand_seed_alg_s-2" /> + <p> + Creates a state object for + <seealso marker="stdlib:rand">random number generation</seealso>, + in order to generate cryptographically unpredictable random numbers. + See also + <seealso marker="#rand_seed_alg-1">rand_seed_alg/1</seealso>. + </p> + <p> + To get a long period the Xoroshiro928 generator from the + <seealso marker="stdlib:rand">rand</seealso> + module is used as a counter (with period 2^928 - 1) + and the generator states are scrambled through AES + to create 58-bit pseudo random values. + </p> + <p> + The result should be statistically completely unpredictable + random values, since the scrambling is cryptographically strong + and the period is ridiculously long. But the generated numbers + are not to be regarded as cryptographically strong since + there is no re-keying schedule. + </p> + <list type="bulleted"> + <item> + <p> + If you need cryptographically strong random numbers use + <seealso marker="#rand_seed_alg_s-1">rand_seed_alg_s/1</seealso> + with <c>Alg =:= crypto</c> or <c>Alg =:= crypto_cache</c>. + </p> + </item> + <item> + <p> + If you need to be able to repeat the sequence use this function. + </p> + </item> + <item> + <p> + If you do not need the statistical quality of this function, + there are faster algorithms in the + <seealso marker="stdlib:rand">rand</seealso> + module. + </p> + </item> + </list> + <p> + Thanks to the used generator the state object supports the + <seealso marker="stdlib:rand#jump-0"><c>rand:jump/0,1</c></seealso> + function with distance 2^512. + </p> + <p> + Numbers are generated in batches and cached for speed reasons. + 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> + </desc> + </func> + + <func> + <name name="ec_curves" arity="0" since="OTP 17.0"/> + <fsummary>Provide a list of available named elliptic curves.</fsummary> + <desc> + <p>Can be used to determine which named elliptic curves are supported.</p> + </desc> + </func> + + <func> + <name name="ec_curve" arity="1" since="OTP 17.0"/> + <fsummary>Get the defining parameters of a elliptic curve.</fsummary> + <desc> + <p>Return the defining parameters of a elliptic curve.</p> + </desc> + </func> + + <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> @@ -646,76 +1583,465 @@ </func> <func> - <name>start() -> ok</name> - <fsummary> Equivalent to application:start(crypto). </fsummary> + <name name="verify" arity="5" since="OTP R16B01"/> + <name name="verify" arity="6" since="OTP 20.1"/> + <fsummary>Verifies a digital signature.</fsummary> <desc> - <p> Equivalent to application:start(crypto).</p> + <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> + + <p>See also <seealso marker="public_key:public_key#verify-4">public_key:verify/4</seealso>.</p> + </desc> + </func> + + </funcs> + <section> + <title>Engine API</title> + </section> + + <funcs> + <!-- 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>stop() -> ok</name> - <fsummary> Equivalent to application:stop(crypto).</fsummary> + <name name="engine_get_all_methods" arity="0" since="OTP 20.2"/> + <fsummary>Return list of all possible engine methods</fsummary> <desc> - <p> Equivalent to application:stop(crypto).</p> + <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>strong_rand_bytes(N) -> binary()</name> - <fsummary>Generate a binary of random bytes</fsummary> + <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> + +<section> + <title>Old API</title> +</section> + + <funcs> + <func> + <name name="block_encrypt" arity="3" since="OTP 18.0"/> + <fsummary>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher</fsummary> + <desc> + <dont><p>Don't use this function for new programs! Use <seealso marker="crypto:new_api">the-new-api</seealso>.</p></dont> + <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 name="block_decrypt" arity="3" since="OTP 18.0"/> + <fsummary>Decrypt <c>CipherText</c> according to <c>Type</c> block cipher</fsummary> + <desc> + <dont><p>Don't use this function for new programs! Use <seealso marker="crypto:new_api">the new api</seealso>.</p></dont> + <p>Decrypt <c>CipherText</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 since="OTP R16B01">block_encrypt(Type, Key, Ivec, PlainText) -> CipherText | Error</name> + <name since="OTP R16B01">block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText, CipherTag} | Error</name> + <name since="OTP R16B01">block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText, TagLength}) -> {CipherText, CipherTag} | Error </name> + <fsummary>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher</fsummary> <type> - <v>N = integer()</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> + <v>Error = <seealso marker="#type-run_time_error">run_time_error()</seealso></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 - failed due to lack of secure "randomness".</p> + <dont><p>Don't use this function for new programs! Use <seealso marker="crypto:new_api">the new api</seealso>.</p></dont> + <p>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher. + <c>IVec</c> is an arbitrary initializing vector.</p> + <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 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>stream_init(Type, Key) -> State</name> - <fsummary></fsummary> + <name since="OTP R16B01">block_decrypt(Type, Key, Ivec, CipherText) -> PlainText | Error</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 = rc4 </v> - <v>State = opaque() </v> - <v>Key = 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>Error = BadTag | <seealso marker="#type-run_time_error">run_time_error()</seealso></v> + <v>BadTag = error</v> </type> <desc> + <dont><p>Don't use this function for new programs! Use <seealso marker="crypto:new_api">the new api</seealso>.</p></dont> + <p>Decrypt <c>CipherText</c> according to <c>Type</c> block cipher. + <c>IVec</c> is an arbitrary initializing vector.</p> + <p>In AEAD (Authenticated Encryption with Associated Data) mode, decrypt + <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 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 name="stream_init" arity="2" since="OTP R16B01"/> + <fsummary></fsummary> + <desc> + <dont><p>Don't use this function for new programs! Use <seealso marker="crypto:new_api">the new api</seealso>.</p></dont> <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#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> + <dont><p>Don't use this function for new programs! Use <seealso marker="crypto:new_api">the new api</seealso>.</p></dont> <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#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> + <dont><p>Don't use this function for new programs! Use <seealso marker="crypto:new_api">the new api</seealso>.</p></dont> <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 <seealso marker="#stream_init-2">stream_init</seealso>. @@ -724,13 +2050,10 @@ </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> + <dont><p>Don't use this function for new programs! Use <seealso marker="crypto:new_api">the new api</seealso>.</p></dont> <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 <seealso marker="#stream_init-2">stream_init</seealso>. @@ -739,136 +2062,130 @@ </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> + <dont><p>Don't use this function for new programs! Use + <seealso marker="crypto#supports-1">supports/1</seealso> in + <seealso marker="crypto:new_api">the new api</seealso>.</p></dont> <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>See <seealso marker="#hash_info-1">hash_info/1</seealso> and <seealso marker="#cipher_info-1">cipher_info/1</seealso> + for information about the hash and cipher algorithms. + </p> </desc> </func> <func> - <name>ec_curves() -> EllipticCurveList </name> - <fsummary>Provide a list of available named elliptic curves.</fsummary> - <type> - <v>EllipticCurveList = [ec_named_curve()]</v> - </type> + <name name="hmac" arity="3" since="OTP R16B"/> + <name name="hmac" arity="4" since="OTP R16B"/> + <fsummary></fsummary> <desc> - <p>Can be used to determine which named elliptic curves are supported.</p> + <dont><p>Don't use this function for new programs! Use + <seealso marker="crypto#mac-4">mac/4</seealso> or + <seealso marker="crypto#macN-5">macN/5</seealso> in + <seealso marker="crypto:new_api">the new api</seealso>.</p> + </dont> + <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> + will limit the size of the resultant <c>Mac</c>.</p> </desc> </func> <func> - <name>ec_curve(NamedCurve) -> EllipticCurve </name> - <fsummary>Get the defining parameters of a elliptic curve.</fsummary> - <type> - <v>NamedCurve = ec_named_curve()</v> - <v>EllipticCurve = ec_explicit_curve()</v> - </type> + <name name="hmac_init" arity="2" since="OTP R14B03"/> + <fsummary></fsummary> <desc> - <p>Return the defining parameters of a elliptic curve.</p> + <dont><p>Don't use this function for new programs! Use + <seealso marker="crypto#mac_init-3">mac_init/3</seealso> in + <seealso marker="crypto:new_api">the new api</seealso>.</p> + </dont> + <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 + key. The key can be any length.</p> </desc> </func> - <func> - <name>verify(Algorithm, DigestType, Msg, Signature, Key) -> boolean()</name> - <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> + <func> + <name name="hmac_update" arity="2" since="OTP R14B03"/> + <fsummary></fsummary> <desc> - <p>Verifies a digital signature</p> - <p>Algorithm <c>dss</c> can only be used together with digest type - <c>sha</c>.</p> + <dont><p>Don't use this function for new programs! Use + <seealso marker="crypto#mac_update-2">mac_update/2</seealso> in + <seealso marker="crypto:new_api">the new api</seealso>.</p> + </dont> + <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 + <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 + <seealso marker="#hmac_final_n-2">hmac_final_n</seealso> + </p> + <warning><p>Do not use a <c>Context</c> as argument in more than one + 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 + libcrypto API.</p></warning> + </desc> + </func> - <p>See also <seealso marker="public_key:public_key#verify-4">public_key:verify/4</seealso>.</p> + <func> + <name name="hmac_final" arity="1" since="OTP R14B03"/> + <fsummary></fsummary> + <desc> + <dont><p>Don't use this function for new programs! Use + <seealso marker="crypto#mac_final-1">mac_final/1</seealso> in + <seealso marker="crypto:new_api">the new api</seealso>.</p> + </dont> + <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> </desc> </func> - </funcs> + <func> + <name name="hmac_final_n" arity="2" since="OTP R14B03"/> + <fsummary></fsummary> + <desc> + <dont><p>Don't use this function for new programs! Use + <seealso marker="crypto#mac_finalN-2">mac_finalN/2</seealso> in + <seealso marker="crypto:new_api">the new api</seealso>.</p> + </dont> + <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> + </desc> + </func> - <!-- 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> + <func> + <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> + <dont><p>Don't use this function for new programs! Use + <seealso marker="crypto#mac-4">mac/4</seealso> or + <seealso marker="crypto#macN-5">macN/5</seealso> in + <seealso marker="crypto:new_api">the new api</seealso>.</p> + </dont> + <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="poly1305" arity="2" since="OTP 21.1"/> + <fsummary></fsummary> + <desc> + <dont><p>Don't use this function for new programs! Use + <seealso marker="crypto#mac-3">mac/3</seealso> or + <seealso marker="crypto#macN-4">macN/4</seealso> in + <seealso marker="crypto:new_api">the new api</seealso>.</p> + </dont> + <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> + + </funcs> + + +</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..f78bb81bba --- /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. Those 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/new_api.xml b/lib/crypto/doc/src/new_api.xml new file mode 100644 index 0000000000..aacf5e4f76 --- /dev/null +++ b/lib/crypto/doc/src/new_api.xml @@ -0,0 +1,329 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2014</year><year>2019</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>New and Old API</title> + <prepared>Hans Nilsson</prepared> + <docno></docno> + <date>2019-08-22</date> + <rev>A</rev> + <file>new_api.xml</file> + </header> + <p> + This chapter describes the new api to encryption and decryption. + </p> + + <section> + <title>Background</title> + <p>The CRYPTO app has evolved during its lifetime. Since also the OpenSSL cryptolib has changed the + API several times, there are parts of the CRYPTO app that uses a very old one internally and + other parts that uses the latest one. The internal definitions of e.g cipher names was a bit hard + to maintain. + </p> + <p>It turned out that using the old api in the new way (more about that later), and still keep it + backwards compatible, was not possible. Specially as more precision in the error messages is desired + it could not be combined with the old standard. + </p> + <p>Therefore the old api (see next section) is kept for now but internally implemented with new primitives. + </p> + </section> + + <section> + <title>The old API</title> + <p>The old functions - not recommended for new programs - are for chipers:</p> + <list> + <item><seealso marker="crypto#block_encrypt-3">block_encrypt/3</seealso></item> + <item><seealso marker="crypto#block_encrypt-4">block_encrypt/4</seealso></item> + <item><seealso marker="crypto#block_decrypt-3">block_decrypt/3</seealso></item> + <item><seealso marker="crypto#block_decrypt-4">block_decrypt/4</seealso></item> + <item><seealso marker="crypto#stream_init-2">stream_init/2</seealso></item> + <item><seealso marker="crypto#stream_init-2">stream_init/3</seealso></item> + <item><seealso marker="crypto#stream_encrypt-2">stream_encrypt/2</seealso></item> + <item><seealso marker="crypto#stream_decrypt-2">stream_decrypt/2</seealso></item> + </list> + <p>for lists of supported algorithms:</p> + <list> + <item><seealso marker="crypto#supports-0">supports/0</seealso></item> + </list> + <p>and for MACs (Message Authentication Codes):</p> + <list> + <item><seealso marker="crypto#cmac-3">cmac/3</seealso></item> + <item><seealso marker="crypto#cmac-4">cmac/4</seealso></item> + <item><seealso marker="crypto#hmac-3">hmac/3</seealso></item> + <item><seealso marker="crypto#hmac-4">hmac/4</seealso></item> + <item><seealso marker="crypto#hmac_init-2">hmac_init/2</seealso></item> + <item><seealso marker="crypto#hmac_update-2">hmac_update/2</seealso></item> + <item><seealso marker="crypto#hmac_final-1">hmac_final/1</seealso></item> + <item><seealso marker="crypto#hmac_final_n-2">hmac_final_n/2</seealso></item> + <item><seealso marker="crypto#poly1305-2">poly1305/2</seealso></item> + </list> + <p>They are not deprecated for now, but may be in a future release. + </p> + </section> + + <section> + <title>The new API</title> + <section> + <title>Encryption and decryption</title> + <p>The new functions for encrypting or decrypting one single binary are: + </p> + <list> + <item><seealso marker="crypto#crypto_one_time/4">crypto_one_time/4</seealso></item> + <item><seealso marker="crypto#crypto_one_time/5">crypto_one_time/5</seealso></item> + <item><seealso marker="crypto#crypto_one_time_aead/6">crypto_one_time_aead/6</seealso></item> + <item><seealso marker="crypto#crypto_one_time_aead/7">crypto_one_time_aead/7</seealso></item> + </list> + <p>In those functions the internal crypto state is first created and initialized + with the cipher type, the key and possibly other data. Then the single binary is encrypted + or decrypted, + the crypto state is de-allocated and the result of the crypto operation is returned. + </p> + <p>The <c>crypto_one_time_aead</c> functions are for the ciphers of mode <c>ccm</c> or + <c>gcm</c>, and for the cipher <c>chacha20-poly1305</c>. + </p> + <p>For repeated encryption or decryption of a text divided in parts, where the internal + crypto state is initialized once, and then many binaries are encrypted or decrypted with + the same state, the functions are: + </p> + <list> + <item><seealso marker="crypto#crypto_init/4">crypto_init/4</seealso></item> + <item><seealso marker="crypto#crypto_init/3">crypto_init/3</seealso></item> + <item><seealso marker="crypto#crypto_update/2">crypto_update/2</seealso></item> + </list> + <p>The <c>crypto_init</c> initialies an internal cipher state, and one or more calls of + <c>crypto_update</c> does the acual encryption or decryption. Note that AEAD ciphers + can't be handled this way due to their nature. + </p> + <p>For repeated encryption or decryption of a text divided in parts where the + same cipher and same key is used, but a new initialization vector (nounce) should be applied + for each part, the functions are: + </p> + <list> + <item><seealso marker="crypto#crypto_dyn_iv_init/3">crypto_dyn_iv_init/3</seealso></item> + <item><seealso marker="crypto#crypto_dyn_iv_update/3">crypto_dyn_iv_update/3</seealso></item> + </list> + <p>An example of where those functions are needed, is when handling the TLS protocol.</p> + <p>For information about available algorithms, use: + </p> + <list> + <item><seealso marker="crypto#supports-1">supports/1</seealso></item> + <item><seealso marker="crypto#hash_info-1">hash_info/1</seealso></item> + <item><seealso marker="crypto#cipher_info-1">cipher_info/1</seealso></item> + </list> + </section> + + <section> + <title>MACs (Message Authentication Codes)</title> + <p>The new functions for calculating a MAC of a single piece of text are:</p> + <list> + <item><seealso marker="crypto#mac-3">mac/3</seealso></item> + <item><seealso marker="crypto#mac-4">mac/4</seealso></item> + <item><seealso marker="crypto#macN-4">macN/4</seealso></item> + <item><seealso marker="crypto#macN-5">macN/5</seealso></item> + </list> + <p>For calculating a MAC of a text divided in parts use:</p> + <list> + <item><seealso marker="crypto#mac_init-2">mac_init/2</seealso></item> + <item><seealso marker="crypto#mac_init-3">mac_init/3</seealso></item> + <item><seealso marker="crypto#mac_update-2">mac_update/2</seealso></item> + <item><seealso marker="crypto#mac_final-1">mac_final/1</seealso></item> + <item><seealso marker="crypto#mac_finalN-2">mac_finalN/2</seealso></item> + </list> + </section> + </section> + + <section> + <title>Examples of the new api</title> + <section> + <title>Examples of crypto_init/4 and crypto_update/2</title> + <p>The functions <seealso marker="crypto#crypto_init/4">crypto_init/4</seealso> + and <seealso marker="crypto#crypto_update/2">crypto_update/2</seealso> are intended + to be used for encrypting or decrypting a sequence of blocks. First one call of + <c>crypto_init/4</c> initialises the crypto context. One or more calls <c>crypto_update/2</c> + does the actual encryption or decryption for each block. + </p> + <p>This example shows first the encryption of two blocks and then decryptions of the cipher + text, but divided into three blocks just to show that it is possible to divide the plain text and + cipher text differently for some ciphers:</p> + <code type="erl"> + 1> crypto:start(). + ok + 2> Key = <<1:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>> + 3> IV = <<0:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0>> + 4> StateEnc = crypto:crypto_init(aes_128_ctr, Key, IV, true). % encrypt -> true + #Ref<0.3768901617.1128660993.124047> + 5> crypto:crypto_update(StateEnc, <<"First bytes">>). + <<67,44,216,166,25,130,203,5,66,6,162>> + 6> crypto:crypto_update(StateEnc, <<"Second bytes">>). + <<16,79,94,115,234,197,94,253,16,144,151,41>> + 7> + 7> StateDec = crypto:crypto_init(aes_128_ctr, Key, IV, false). % decrypt -> false + #Ref<0.3768901617.1128660994.124255> + 8> crypto:crypto_update(StateDec, <<67,44,216,166,25,130,203>>). + <<"First b">> + 9> crypto:crypto_update(StateDec, <<5,66,6,162,16,79,94,115,234,197, + 94,253,16,144,151>>). + <<"ytesSecond byte">> + 10> crypto:crypto_update(StateDec, <<41>>). + <<"s">> + 11> + </code> + <p>Note that the internal data that the <c>StateEnc</c> and <c>StateDec</c> references are + destructivly updated by the calls to <seealso marker="crypto#crypto_update/2">crypto_update/2</seealso>. + This is to gain time in the calls of the nifs interfacing the cryptolib. In a loop where the + state is saved in the loop's state, it also saves one update of the loop state per crypto operation. + </p> + <p>For example, a simple server receiving text parts to encrypt and send the result back to the + one who sent them (the <c>Requester</c>): + </p> + <code type="erl"> + encode(Crypto, Key, IV) -> + crypto_loop(crypto:crypto_init(Crypto, Key, IV, true)). + + crypto_loop(State) -> + receive + {Text, Requester} -> + Requester ! crypto:crypto_update(State, Text), + loop(State) + end. + </code> + </section> + + <section> + <title>Example of crypto_one_time/5</title> + <p>The same example as in the + <seealso marker="#examples-of-crypto_init-4-and-crypto_update-2">previous section</seealso>, + but now with one call to <seealso marker="crypto#crypto_one_time/5">crypto_one_time/5</seealso>: + </p> + <code> + 1> Key = <<1:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>> + 2> IV = <<0:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0>> + 3> Txt = [<<"First bytes">>,<<"Second bytes">>]. + [<<"First bytes">>,<<"Second bytes">>] + 4> crypto:crypto_one_time(aes_128_ctr, Key, IV, Txt, true). + <<67,44,216,166,25,130,203,5,66,6,162,16,79,94,115,234, + 197,94,253,16,144,151,41>> + 5> + </code> + <p>The <c>[<<"First bytes">>,<<"Second bytes">>]</c> could of course have been one + single binary: <c><<"First bytesSecond bytes">></c>. + </p> + </section> + + <section> + <title>Example of crypto_one_time_aead/6</title> + <p>The same example as in the + <seealso marker="#example-of-crypto_one_time-5">previous section</seealso>, + but now with one call to <seealso marker="crypto#crypto_one_time_aead/6">crypto_one_time_aead/6</seealso>: + </p> + <code> + 1> Key = <<1:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>> + 2> IV = <<0:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0>> + 3> Txt = [<<"First bytes">>,<<"Second bytes">>]. + [<<"First bytes">>,<<"Second bytes">>] + 4> AAD = <<"Some bytes">>. + <<"Some bytes">> + 5> crypto:crypto_one_time_aead(aes_128_gcm, Key, IV, Txt, AAD, true). + {<<240,130,38,96,130,241,189,52,3,190,179,213,132,1,72, + 192,103,176,90,104,15,71,158>>, + <<131,47,45,91,142,85,9,244,21,141,214,71,31,135,2,155>>} + 9> + </code> + <p>The <c>[<<"First bytes">>,<<"Second bytes">>]</c> could of course have been one + single binary: <c><<"First bytesSecond bytes">></c>. + </p> + </section> + + <section> + <title>Example of mac_init mac_update and mac_final</title> + <code> + 1> Key = <<1:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>> + 2> StateMac = crypto:mac_init(cmac, aes_128_cbc, Key). + #Ref<0.2424664121.2781478916.232610> + 3> crypto:mac_update(StateMac, <<"First bytes">>). + #Ref<0.2424664121.2781478916.232610> + 4> crypto:mac_update(StateMac, " "). + #Ref<0.2424664121.2781478916.232610> + 5> crypto:mac_update(StateMac, <<"last bytes">>). + #Ref<0.2424664121.2781478916.232610> + 6> crypto:mac_final(StateMac). + <<68,191,219,128,84,77,11,193,197,238,107,6,214,141,160, + 249>> + 7> + </code> + <p>and compare the result with a single calculation just for this example:</p> + <code> + 7> crypto:mac(cmac, aes_128_cbc, Key, "First bytes last bytes"). + <<68,191,219,128,84,77,11,193,197,238,107,6,214,141,160, + 249>> + 8> v(7) == v(6). + true + 9> + </code> + </section> + + </section> + + <section> + <title>Retired cipher names</title> + <p>This table lists the retired cipher names in the first column and suggests names to replace them with + in the second column. + </p> + <p>The new names follows the OpenSSL libcrypto names. The format is ALGORITM_KEYSIZE_MODE. + </p> + <p>Examples of algorithms are aes, chacha20 and des. The keysize is the number of bits + and examples of the mode are cbc, ctr and gcm. The mode may be followed by a number depending + on the mode. An example is the ccm mode which has a variant called ccm8 where the so called tag + has a length of eight bits. + </p> + <p>The old names had by time lost any common naming convention which the new names now introduces. The new names include + the key length which improves the error checking in the lower levels of the crypto application. + </p> + + <table> + <row><cell><strong>Instead of:</strong></cell> <cell><strong>Use:</strong> </cell></row> + + <row><cell><c>aes_cbc128</c> </cell> <cell> <c>aes_128_cbc</c> </cell></row> + <row><cell><c>aes_cbc256</c> </cell> <cell> <c>aes_256_cbc</c> </cell></row> + <row><cell><c>aes_cbc</c> </cell> <cell> <c>aes_128_cbc, aes_192_cbc, aes_256_cbc</c></cell></row> + <row><cell><c>aes_ccm</c> </cell> <cell> <c>aes_128_ccm, aes_192_ccm, aes_256_ccm</c></cell></row> + <row><cell><c>aes_cfb128</c> </cell> <cell> <c>aes_128_cfb128, aes_192_cfb128, aes_256_cfb128</c></cell></row> + <row><cell><c>aes_cfb8</c> </cell> <cell> <c>aes_128_cfb8, aes_192_cfb8, aes_256_cfb8</c></cell></row> + <row><cell><c>aes_ctr</c> </cell> <cell> <c>aes_128_ctr, aes_192_ctr, aes_256_ctr</c></cell></row> + <row><cell><c>aes_gcm</c> </cell> <cell> <c>aes_128_gcm, aes_192_gcm, aes_256_gcm</c></cell></row> + <row><cell><c>des3_cbc</c> </cell> <cell> <c>des_ede3_cbc</c></cell></row> + <row><cell><c>des3_cbf</c> </cell> <cell> <c>des_ede3_cfb</c></cell></row> + <row><cell><c>des3_cfb</c> </cell> <cell> <c>des_ede3_cfb</c></cell></row> + <row><cell><c>des_ede3</c> </cell> <cell> <c>des_ede3_cbc</c></cell></row> + <row><cell><c>des_ede3_cbf</c> </cell> <cell> <c>des_ede3_cfb</c></cell></row> + <tcaption></tcaption> + </table> + </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..5f47981855 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,742 @@ </header> <p>This document describes the changes made to the Crypto application.</p> +<section><title>Crypto 4.5.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The cipher aes-ctr was disabled by misstake in + crypto:supports for cryptolibs before 1.0.1. It worked + however in the encrypt and decrypt functions.</p> + <p> + Own Id: OTP-15829</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed a bug in error return for <c>crypto:poly1305/2</c>. + It returned the atom <c>notsup</c> instead of the + exception <c>notsup</c>.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15677</p> + </item> + <item> + <p> + The cipher chacha20 was introduced in OpenSSL 1.1.0. + However, it could in a very odd situation, fail for + versions less than OpenSSL 1.1.0d. It is therefore + disabled for those versions.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15678</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> A new <c>rand</c> module algorithm, <c>exro928ss</c> + (Xoroshiro928**), has been implemented. It has got a + really long period and good statistical quality for all + output bits, while still being only about 50% slower than + the default algorithm. </p><p> The same generator is also + used as a long period counter in a new <c>crypto</c> + plugin for the <c>rand</c> module, algorithm + <c>crypto_aes</c>. This plugin uses AES-256 to scramble + the counter which buries any detectable statistical + artifacts. Scrambling is done in chunks which are cached + to get good amortized speed (about half of the default + algorithm). </p> + <p> + Own Id: OTP-14461 Aux Id: PR-1857 </p> + </item> + <item> + <p> + Crypto's single C-file is split into multiple files. The + different coding styles in the different parts are + unified into a single style.</p> + <p> + Own Id: OTP-14732 Aux Id: PR-2068, PR-2095 </p> + </item> + <item> + <p> + Build configuration of the <c>crypto</c> application has + been moved from the <c>erts</c> application into the + <c>crypto</c> application.</p> + <p> + Own Id: OTP-15129</p> + </item> + <item> + <p> + Adds two hash functions <c>blake2b</c> and <c>blake2s</c> + (64 bit hash and 32 bit hash respectively). These are + modern and standard hash functions used in blockchains + and encrypted communication protocols. The hash functions + are available in OpenSSL since version 1.1.1.</p> + <p> + Own Id: OTP-15564 Aux Id: PR-2129 </p> + </item> + <item> + <p> + A new API is implemented in crypto. See the CRYPTO user's + guide, chapter <i>New and Old API</i> for more + information.</p> + <p> + The old api with the <c>crypto:block_*</c> and + <c>crypto:stream_*</c> interfaces are kept for + compatibility, but implemented with the new api. Please + note that since the error checking is more thorough, + there <i>might</i> be arguments with for example faulty + lengths that are no longer accepted.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15644 Aux Id: OTP-14732 , OTP-15451, PR-1857 + , PR-2068, PR-2095 </p> + </item> + <item> + <p> + The new hash_info/1 and cipher_info/1 functions returns + maps with information about the hash or cipher in the + argument.</p> + <p> + Own Id: OTP-15655 Aux Id: PR-2173, ERL-864, PR-2186 </p> + </item> + <item> + <p> + Obey additional OpenSSL configure flags when compiling + the C-part of the CRYPTO application: <c>no-bf</c>, + <c>no-blake2</c>, <c>no-chacha</c>, <c>no-cmac</c>, + <c>no-dh</c>, <c>no-dsa</c>, <c>no-md4</c>, + <c>no-poly1305</c>, <c>no-rc2</c>, <c>no-rc4</c> and + <c>no-rmd160</c>.</p> + <p> + Own Id: OTP-15683</p> + </item> + <item> + <p> + A new function <c>crypto:supports/1</c> is introduced. + The single argument takes an atom as argument: + <c>hashes</c>, <c>public_keys</c>, <c>ciphers</c>, + <c>macs</c>, <c>curves</c> or <c>rsa_opts</c>. The return + value is a list of supported algorithms.</p> + <p> + The difference with the existing <c>crypto:supports/0</c> + is, apart from the argument and the return value, that + the old function reports what is supported by the old + api, and the new function reports algorithms in the new + api.</p> + <p> + Own Id: OTP-15771</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 4.4.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed build link error on Windows. Unresolved symbol + 'bcmp'.</p> + <p> + Own Id: OTP-15750 Aux Id: ERL-905 </p> + </item> + </list> + </section> + +</section> + +<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..134f900d4c 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,9 @@ </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"/> + <xi:include href="new_api.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 |
