diff options
Diffstat (limited to 'lib/crypto/doc/src')
| -rw-r--r-- | lib/crypto/doc/src/Makefile | 21 | ||||
| -rw-r--r-- | lib/crypto/doc/src/book.xml | 25 | ||||
| -rw-r--r-- | lib/crypto/doc/src/crypto.xml | 273 | ||||
| -rw-r--r-- | lib/crypto/doc/src/crypto_app.xml | 25 | ||||
| -rw-r--r-- | lib/crypto/doc/src/fascicules.xml | 2 | ||||
| -rw-r--r-- | lib/crypto/doc/src/insidecover.xml | 2 | ||||
| -rw-r--r-- | lib/crypto/doc/src/licenses.xml | 25 | ||||
| -rw-r--r-- | lib/crypto/doc/src/notes.xml | 399 | ||||
| -rw-r--r-- | lib/crypto/doc/src/ref_man.xml | 25 | ||||
| -rw-r--r-- | lib/crypto/doc/src/release_notes.xml | 23 | ||||
| -rw-r--r-- | lib/crypto/doc/src/usersguide.xml | 25 |
11 files changed, 662 insertions, 183 deletions
diff --git a/lib/crypto/doc/src/Makefile b/lib/crypto/doc/src/Makefile index 00ae70fb4a..e55242d255 100644 --- a/lib/crypto/doc/src/Makefile +++ b/lib/crypto/doc/src/Makefile @@ -1,13 +1,14 @@ -# ``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 via the world wide web 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. +# ``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 +# distributed under the License is distributed on an "AS IS" BASIS, +# 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 diff --git a/lib/crypto/doc/src/book.xml b/lib/crypto/doc/src/book.xml index f07208482c..b8b2c935b3 100644 --- a/lib/crypto/doc/src/book.xml +++ b/lib/crypto/doc/src/book.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE book SYSTEM "book.dtd"> <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header titlestyle="normal"> <copyright> - <year>1999</year><year>2009</year> + <year>1999</year><year>2016</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. + 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 + distributed under the License is distributed on an "AS IS" BASIS, + 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> diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 99d167bfa9..5a5627747c 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1999</year><year>2013</year> + <year>1999</year><year>2016</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. + 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 + distributed under the License is distributed on an "AS IS" BASIS, + 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> @@ -41,7 +42,7 @@ </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 and CTR </url></p> + 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> @@ -53,35 +54,41 @@ <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> </description> <section> <title>DATA TYPES </title> - <p><code>key_value() = integer() | binary() </code></p> + <code>key_value() = integer() | binary() </code> <p>Always <c>binary()</c> when used as return value</p> - <p><code>rsa_public() = [key_value()] = [E, N] </code></p> + <code>rsa_public() = [key_value()] = [E, N] </code> <p> Where E is the public exponent and N is public modulus. </p> - <p><code>rsa_private() = [key_value()] = [E, N, D] | [E, N, D, P1, P2, E1, E2, C] </code></p> + <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> - <p><code>dss_public() = [key_value()] = [P, Q, G, Y] </code></p> + <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> - <p><code>dss_private() = [key_value()] = [P, Q, G, X] </code></p> + <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> - <p><code>srp_public() = key_value() </code></p> + <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> - <p><code>srp_private() = key_value() </code></p> + <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> <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 @@ -89,94 +96,154 @@ Version = '3' | '6' | '6a' </p> - <p><code>dh_public() = key_value() </code></p> + <code>dh_public() = key_value() </code> + + <code>dh_private() = key_value() </code> - <p><code>dh_private() = key_value() </code></p> + <code>dh_params() = [key_value()] = [P, G] </code> - <p><code>dh_params() = [key_value()] = [P, G] </code></p> + <code>ecdh_public() = key_value() </code> - <p><code>ecdh_public() = key_value() </code></p> + <code>ecdh_private() = key_value() </code> - <p><code>ecdh_private() = key_value() </code></p> + <code>ecdh_params() = ec_named_curve() | ec_explicit_curve()</code> - <p><code>ecdh_params() = ec_named_curve() | - {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(), CoFactor :: none | integer()} </code></p> + <code>ec_explicit_curve() = + {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(), CoFactor :: none | integer()} </code> - <p><code>ec_field() = {prime_field, Prime :: integer()} | - {characteristic_two_field, M :: integer(), Basis :: ec_basis()}</code></p> + <code>ec_field() = {prime_field, Prime :: integer()} | + {characteristic_two_field, M :: integer(), Basis :: ec_basis()}</code> - <p><code>ec_basis() = {tpbasis, K :: non_neg_integer()} | + <code>ec_basis() = {tpbasis, K :: non_neg_integer()} | {ppbasis, K1 :: non_neg_integer(), K2 :: non_neg_integer(), K3 :: non_neg_integer()} | - onbasis</code></p> + onbasis</code> - <p><code>ec_named_curve() -> + <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 </code></p> + 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>stream_cipher() = rc4 | aes_ctr </code> - <p><code>stream_cipher() = rc4 | aes_ctr </code></p> + <code>block_cipher() = aes_cbc | aes_cfb8 | aes_cfb128 | aes_ige256 | blowfish_cbc | + blowfish_cfb64 | des_cbc | des_cfb | des3_cbc | des3_cbf | des_ede3 | rc2_cbc </code> - <p><code>block_cipher() = aes_cbc128 | aes_cfb128 | blowfish_cbc | - blowfish_cfb64 | des_cbc | des_cfb | des3_cbc | des3_cbf - | des_ede3 | rc2_cbc </code></p> + <code>aead_cipher() = aes_gcm | chacha20_poly1305 </code> - <p><code>stream_key() = aes_key() | rc4_key() </code></p> + <code>stream_key() = aes_key() | rc4_key() </code> - <p><code>block_key() = aes_key() | blowfish_key() | des_key()| des3_key() </code></p> + <code>block_key() = aes_key() | blowfish_key() | des_key()| des3_key() </code> - <p><code>aes_key() = iodata() </code> Key length is 128, 192 or 256 bits</p> + <code>aes_key() = iodata() </code> <p>Key length is 128, 192 or 256 bits</p> - <p><code>rc4_key() = iodata() </code> Variable key length from 8 bits up to 2048 bits (usually between 40 and 256)</p> + <code>rc4_key() = iodata() </code> <p>Variable key length from 8 bits up to 2048 bits (usually between 40 and 256)</p> - <p><code>blowfish_key() = iodata() </code> Variable key length from 32 bits up to 448 bits</p> + <code>blowfish_key() = iodata() </code> <p>Variable key length from 32 bits up to 448 bits</p> - <p><code>des_key() = iodata() </code> Key length is 64 bits (in CBC mode only 8 bits are used)</p> + <code>des_key() = iodata() </code> <p>Key length is 64 bits (in CBC mode only 8 bits are used)</p> - <p><code>des3_key() = [binary(), binary(), binary()] </code> Each key part is 64 bits (in CBC mode only 8 bits are used)</p> + <code>des3_key() = [binary(), binary(), binary()] </code> <p>Each key part is 64 bits (in CBC mode only 8 bits are used)</p> - <p><code>digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512</code></p> + <code>digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512</code> - <p><code> hash_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 </code> md4 is also supported for hash_init/1 and hash/2. + <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> - <p><code> cipher_algorithms() = des_cbc | des_cfb | des3_cbc | des3_cbf | des_ede3 | - blowfish_cbc | blowfish_cfb64 | aes_cbc128 | aes_cfb128| aes_cbc256 | rc2_cbc | aes_ctr| rc4 </code> </p> - <p><code> public_key_algorithms() = rsa |dss | ecdsa | dh | ecdh </code> </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_cbf | 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> + </section> <funcs> - <func> + <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> + <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> + </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> + <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> + </desc> + </func> + + <func> <name>block_encrypt(Type, Key, Ivec, PlainText) -> CipherText</name> - <fsummary>Encrypt <c>PlainText</c>according to <c>Type</c> block cipher</fsummary> + <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>IVec = CipherText = binary()</v> + <v>AAD = IVec = CipherText = CipherTag = binary()</v> + <v>TagLength = 1..16</v> </type> <desc> - <p>Encrypt <c>PlainText</c>according to <c>Type</c> block cipher. - <c>IVec</c> is an arbitrary initializing vector. - </p> + <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> </desc> </func> <func> <name>block_decrypt(Type, Key, Ivec, CipherText) -> PlainText</name> - <fsummary>Decrypt <c>CipherText</c>according to <c>Type</c> block cipher</fsummary> + <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>IVec = CipherText = binary()</v> + <v>AAD = IVec = CipherText = CipherTag = binary()</v> </type> <desc> - <p>Decrypt <c>CipherText</c>according to <c>Type</c> block cipher. - <c>IVec</c> is an arbitrary initializing vector. - </p> + <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> </desc> </func> @@ -235,12 +302,14 @@ <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() | srp_private() </v> + <v>PrivKeyIn = undefined | dh_private() | ecdh_private() | srp_private() </v> <v>PrivKeyOut = dh_private() | ecdh_private() | srp_private() </v> </type> <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> </desc> </func> @@ -316,8 +385,8 @@ </type> <desc> <p>Computes a HMAC of type <c>Type</c> from <c>Data</c> using - <c>Key</c> as the authentication key.</p> <c>MacLength</c> - will limit the size of the resultant <c>Mac</c>. + <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> @@ -351,7 +420,11 @@ 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 + OpenSSL API.</p></warning> </desc> </func> @@ -437,17 +510,17 @@ </func> <func> - <name>private_decrypt(Type, ChipherText, PrivateKey, Padding) -> PlainText</name> - <fsummary>Decrypts ChipherText using the private Key.</fsummary> + <name>private_decrypt(Type, CipherText, PrivateKey, Padding) -> PlainText</name> + <fsummary>Decrypts CipherText using the private Key.</fsummary> <type> <v>Type = rsa</v> - <v>ChipherText = binary()</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>ChipherText</c>, encrypted with + <p>Decrypts the <c>CipherText</c>, encrypted with <seealso marker="#public_encrypt-4">public_encrypt/4</seealso> (or equivalent function) using the <c>PrivateKey</c>, and returns the plaintext (message digest). This is a low level signature verification operation @@ -458,7 +531,7 @@ </func> <func> - <name>private_encrypt(Type, PlainText, PrivateKey, Padding) -> ChipherText</name> + <name>private_encrypt(Type, PlainText, PrivateKey, Padding) -> CipherText</name> <fsummary>Encrypts PlainText using the private Key.</fsummary> <type> <v>Type = rsa</v> @@ -469,7 +542,7 @@ 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>ChipherText = binary()</v> + <v>CipherText = binary()</v> </type> <desc> <p>Encrypts the <c>PlainText</c> using the <c>PrivateKey</c> @@ -481,17 +554,17 @@ </desc> </func> <func> - <name>public_decrypt(Type, ChipherText, PublicKey, Padding) -> PlainText</name> - <fsummary>Decrypts ChipherText using the public Key.</fsummary> + <name>public_decrypt(Type, CipherText, PublicKey, Padding) -> PlainText</name> + <fsummary>Decrypts CipherText using the public Key.</fsummary> <type> <v>Type = rsa</v> - <v>ChipherText = binary()</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>ChipherText</c>, encrypted with + <p>Decrypts the <c>CipherText</c>, encrypted with <seealso marker="#private_encrypt-4">private_encrypt/4</seealso>(or equivalent function) using the <c>PrivateKey</c>, and returns the plaintext (message digest). This is a low level signature verification operation @@ -502,7 +575,7 @@ </func> <func> - <name>public_encrypt(Type, PlainText, PublicKey, Padding) -> ChipherText</name> + <name>public_encrypt(Type, PlainText, PublicKey, Padding) -> CipherText</name> <fsummary>Encrypts PlainText using the public Key.</fsummary> <type> <v>Type = rsa</v> @@ -513,7 +586,7 @@ 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>ChipherText = binary()</v> + <v>CipherText = binary()</v> </type> <desc> <p>Encrypts the <c>PlainText</c> (message digest) using the <c>PublicKey</c> @@ -525,15 +598,17 @@ </func> <func> - <name>rand_bytes(N) -> binary()</name> - <fsummary>Generate a binary of random bytes</fsummary> + <name>rand_seed(Seed) -> ok</name> + <fsummary>Set the seed for random bytes generation</fsummary> <type> - <v>N = integer()</v> + <v>Seed = binary()</v> </type> <desc> - <p>Generates N bytes randomly uniform 0..255, and returns the - result in a binary. Uses the <c>crypto</c> library pseudo-random - number generator.</p> + <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> </desc> </func> @@ -566,7 +641,7 @@ <p>Creates a digital signature.</p> <p>Algorithm <c>dss</c> can only be used together with digest type <c>sha</c>.</p> - See also <seealso marker="public_key:public_key#sign-3">public_key:sign/3</seealso> + <p>See also <seealso marker="public_key:public_key#sign-3">public_key:sign/3</seealso>.</p> </desc> </func> @@ -626,7 +701,7 @@ </type> <desc> <p>Initializes the state for use in streaming AES encryption using Counter mode (CTR). - <c>Key</c> is the AES key and must be either 128, 192, or 256 bts long. <c>IVec</c> is + <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> @@ -659,7 +734,7 @@ <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>. - <c>NewState</c> must be passed into the next call to <c>stream_encrypt</c>.</p> + <c>NewState</c> must be passed into the next call to <c>stream_decrypt</c>.</p> </desc> </func> @@ -678,7 +753,29 @@ </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> + <desc> + <p>Can be used to determine which named elliptic curves are supported.</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> + <desc> + <p>Return the defining parameters of a elliptic curve.</p> + </desc> + </func> + <func> <name>verify(Algorithm, DigestType, Msg, Signature, Key) -> boolean()</name> <fsummary>Verifies a digital signature.</fsummary> @@ -696,7 +793,7 @@ <p>Algorithm <c>dss</c> can only be used together with digest type <c>sha</c>.</p> - See also <seealso marker="public_key:public_key#verify-4">public_key:verify/4</seealso> + <p>See also <seealso marker="public_key:public_key#verify-4">public_key:verify/4</seealso>.</p> </desc> </func> diff --git a/lib/crypto/doc/src/crypto_app.xml b/lib/crypto/doc/src/crypto_app.xml index 6d26076c04..2b9e505988 100644 --- a/lib/crypto/doc/src/crypto_app.xml +++ b/lib/crypto/doc/src/crypto_app.xml @@ -1,24 +1,25 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE appref SYSTEM "appref.dtd"> <appref> <header> <copyright> <year>1999</year> - <year>2013</year> + <year>2016</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. + 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 + distributed under the License is distributed on an "AS IS" BASIS, + 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 AB. </legalnotice> diff --git a/lib/crypto/doc/src/fascicules.xml b/lib/crypto/doc/src/fascicules.xml index 8fc250bc75..cbc266cd30 100644 --- a/lib/crypto/doc/src/fascicules.xml +++ b/lib/crypto/doc/src/fascicules.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE fascicules SYSTEM "fascicules.dtd"> <fascicules> diff --git a/lib/crypto/doc/src/insidecover.xml b/lib/crypto/doc/src/insidecover.xml index e7407b8052..bf2427afdf 100644 --- a/lib/crypto/doc/src/insidecover.xml +++ b/lib/crypto/doc/src/insidecover.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE bookinsidecover SYSTEM "bookinsidecover.dtd"> <bookinsidecover> diff --git a/lib/crypto/doc/src/licenses.xml b/lib/crypto/doc/src/licenses.xml index 0b791acfa2..e5c06cf7ce 100644 --- a/lib/crypto/doc/src/licenses.xml +++ b/lib/crypto/doc/src/licenses.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2003</year><year>2011</year> + <year>2003</year><year>2016</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. + 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 + distributed under the License is distributed on an "AS IS" BASIS, + 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> diff --git a/lib/crypto/doc/src/notes.xml b/lib/crypto/doc/src/notes.xml index 09ecc97ef7..7d3a85326f 100644 --- a/lib/crypto/doc/src/notes.xml +++ b/lib/crypto/doc/src/notes.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>1999</year><year>2013</year> + <year>1999</year><year>2016</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. + 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 + distributed under the License is distributed on an "AS IS" BASIS, + 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> @@ -30,6 +31,380 @@ </header> <p>This document describes the changes made to the Crypto application.</p> +<section><title>Crypto 3.7</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Refactor <c>crypto</c> to use the EVP interface of + OpenSSL, which is the recommended interface that also + enables access to hardware acceleration for some + operations.</p> + <p> + Own Id: OTP-12217</p> + </item> + <item> + <p> + Add support for 192-bit keys for the <c>aes_cbc</c> + cipher.</p> + <p> + Own Id: OTP-13206 Aux Id: pr 832 </p> + </item> + <item> + <p> + Add support for 192-bit keys for <c>aes_ecb</c>.</p> + <p> + Own Id: OTP-13207 Aux Id: pr829 </p> + </item> + <item> + <p> + Deprecate the function <c>crypto:rand_bytes</c> and make + sure that <c>crypto:strong_rand_bytes</c> is used in all + places that are cryptographically significant.</p> + <p> + Own Id: OTP-13214</p> + </item> + <item> + <p> + Enable AES-GCM encryption/decryption to change the tag + length between 1 to 16 bytes.</p> + <p> + Own Id: OTP-13483 Aux Id: PR-998 </p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.6.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix bug for <c>aes_ecb</c> block crypto when data is + larger than 16 bytes.</p> + <p> + Own Id: OTP-13249</p> + </item> + <item> + <p> + Improve portability of ECC tests in Crypto and SSL for + "exotic" OpenSSL versions.</p> + <p> + Own Id: OTP-13311</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.6.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Small documentation fixes</p> + <p> + Own Id: OTP-13017</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.6.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Make <c>crypto:ec_curves/0</c> return empty list if + elliptic curve is not supported at all.</p> + <p> + Own Id: OTP-12944</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Enhance crypto:generate_key to calculate ECC public keys + from private key.</p> + <p> + Own Id: OTP-12394</p> + </item> + <item> + <p> + Fix bug in <c>crypto:generate_key</c> for <c>ecdh</c> + that could cause VM crash for faulty input.</p> + <p> + Own Id: OTP-12733</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Use the EVP API for AES-CBC crypto to enables the use of + hardware acceleration for AES-CBC crypto on newer Intel + CPUs (AES-NI), among other platforms.</p> + <p> + Own Id: OTP-12380</p> + </item> + <item> + <p> + Add AES ECB block encryption.</p> + <p> + Own Id: OTP-12403</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.5</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Extend block_encrypt/decrypt for aes_cfb8 and aes_cfb128 + to accept keys of length 128, 192 and 256 bits. Before + only 128 bit keys were accepted.</p> + <p> + Own Id: OTP-12467</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.4.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add configure option --with-ssl-incl=PATH to support + OpenSSL installations with headers and libraries at + different places.</p> + <p> + Own Id: OTP-12215 Aux Id: seq12700 </p> + </item> + <item> + <p> + Add configure option --with-ssl-rpath to control which + runtime library path to use for dynamic linkage toward + OpenSSL.</p> + <p> + Own Id: OTP-12316 Aux Id: seq12753 </p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.4.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Make <c>crypto</c> verify major version number of OpenSSL + header files and runtime library. Loading of + <c>crypto</c> will fail if there is a version mismatch.</p> + <p> + Own Id: OTP-12146 Aux Id: seq12700 </p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix memory leak in <c>crypto:hmac_init/upgrade/final</c> + functions for all data and in <c>crypto:hmac/3/4</c> for + data larger than 20000 bytes. Bug exists since OTP 17.0.</p> + <p> + Own Id: OTP-11953</p> + </item> + <item> + <p> + Fix memory leak in <c>crypto</c> for elliptic curve.</p> + <p> + Own Id: OTP-11999</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add <c>aes_cfb8</c> cypher to <c>crypto:block_encrypt</c> + and <c>block_decrypt</c>.</p> + <p> + Own Id: OTP-11911</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix memory leaks and invalid deallocations in + <c>mod_pow</c>, <c>mod_exp</c> and + <c>generate_key(srp,...)</c> when bad arguments are + passed. (Thanks to Florian Zumbiehi)</p> + <p> + Own Id: OTP-11550</p> + </item> + <item> + <p> + Correction of the word 'ChipherText' throughout the + documentation (Thanks to Andrew Tunnell-Jones)</p> + <p> + Own Id: OTP-11609</p> + </item> + <item> + <p> + Fix fatal bug when using a hmac context variable in more + than one call to <c>hmac_update</c> or <c>hmac_final</c>. + The reuse of hmac contexts has never worked as the + underlying OpenSSL implementation does not support it. It + is now documented as having undefined behaviour, but it + does not crash or corrupt the VM anymore.</p> + <p> + Own Id: OTP-11724</p> + </item> + <item> + <p> + Crypto handles out-of-memory with a controlled abort + instead of crash/corruption. (Thanks to Florian Zumbiehi)</p> + <p> + Own Id: OTP-11725</p> + </item> + <item> + <p> + Application upgrade (appup) files are corrected for the + following applications: </p> + <p> + <c>asn1, common_test, compiler, crypto, debugger, + dialyzer, edoc, eldap, erl_docgen, et, eunit, gs, hipe, + inets, observer, odbc, os_mon, otp_mibs, parsetools, + percept, public_key, reltool, runtime_tools, ssh, + syntax_tools, test_server, tools, typer, webtool, wx, + xmerl</c></p> + <p> + A new test utility for testing appup files is added to + test_server. This is now used by most applications in + OTP.</p> + <p> + (Thanks to Tobias Schlager)</p> + <p> + Own Id: OTP-11744</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + By giving --enable-static-{nifs,drivers} to configure it + is now possible to statically linking of nifs and drivers + to the main Erlang VM binary. At the moment only the asn1 + and crypto nifs of the Erlang/OTP nifs and drivers have + been prepared to be statically linked. For more details + see the Installation Guide in the System documentation.</p> + <p> + Own Id: OTP-11258</p> + </item> + <item> + <p> + Add IGE mode for AES cipher in crypto (Thanks to Yura + Beznos).</p> + <p> + Own Id: OTP-11522</p> + </item> + <item> + <p> + Moved elliptic curve definition from the crypto + NIF/OpenSSL into Erlang code, adds the RFC-5639 brainpool + curves and makes TLS use them (RFC-7027).</p> + <p> + Thanks to Andreas Schultz</p> + <p> + Own Id: OTP-11578</p> + </item> + <item> + <p> + Remove all obsolete application processes from crypto and + make it into a pure library application.</p> + <p> + Own Id: OTP-11619</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix uninitialized pointers in crypto (Thanks to Anthony + Ramine)</p> + <p> + Own Id: OTP-11510</p> + </item> + </list> + </section> + +</section> + +<section><title>Crypto 3.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Refactor ecdsa cipher to simplify code and improve + performance.</p> + <p> + Own Id: OTP-11320</p> + </item> + </list> + </section> + +</section> + <section><title>Crypto 3.0</title> <section><title>Improvements and New Features</title> diff --git a/lib/crypto/doc/src/ref_man.xml b/lib/crypto/doc/src/ref_man.xml index f801221c81..14922cbcec 100644 --- a/lib/crypto/doc/src/ref_man.xml +++ b/lib/crypto/doc/src/ref_man.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE application SYSTEM "application.dtd"> <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1999</year><year>2009</year> + <year>1999</year><year>2016</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. + 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 + distributed under the License is distributed on an "AS IS" BASIS, + 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> diff --git a/lib/crypto/doc/src/release_notes.xml b/lib/crypto/doc/src/release_notes.xml index 0a84ca1c15..a2d7964455 100644 --- a/lib/crypto/doc/src/release_notes.xml +++ b/lib/crypto/doc/src/release_notes.xml @@ -1,24 +1,25 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part> <header> <copyright> <year>1999</year> - <year>2011</year> + <year>2016</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/. + 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 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + 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 AB. </legalnotice> diff --git a/lib/crypto/doc/src/usersguide.xml b/lib/crypto/doc/src/usersguide.xml index dc5bf520a9..fb088a8285 100644 --- a/lib/crypto/doc/src/usersguide.xml +++ b/lib/crypto/doc/src/usersguide.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2003</year><year>2009</year> + <year>2003</year><year>2016</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. + 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 + distributed under the License is distributed on an "AS IS" BASIS, + 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> |