From 5f05cfb309bcbdc1e9444086b7c920739e389215 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Fri, 14 Jun 2019 12:26:54 +0200 Subject: crypto: Modernized 'Algorithms' section in User's Guide Adapted to the "New API" introduced in 22.0 --- lib/crypto/doc/src/algorithm_details.xml | 233 ++++++++++++++++++++----------- lib/crypto/doc/src/crypto.xml | 38 ++++- 2 files changed, 185 insertions(+), 86 deletions(-) diff --git a/lib/crypto/doc/src/algorithm_details.xml b/lib/crypto/doc/src/algorithm_details.xml index 85ae766c35..71014764c8 100644 --- a/lib/crypto/doc/src/algorithm_details.xml +++ b/lib/crypto/doc/src/algorithm_details.xml @@ -37,81 +37,129 @@
Ciphers +

A cipher in the + new api + is categorized as either + cipher_no_iv(), + cipher_iv() or + cipher_aead(). + The letters IV are short for Initialization Vector and + AEAD is an abreviation of Authenticated Encryption with Associated Data. +

+

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 + Retired cipher names. +

+

To dynamically check availability, check that the name in the Cipher and Mode column is present in the + list returned by crypto:supports(ciphers). +

+
- Block Ciphers -

To be used in - block_encrypt/3, - block_encrypt/4, - block_decrypt/3 and - block_decrypt/4. -

-

Available in all OpenSSL compatible with Erlang CRYPTO if not disabled by configuration. + Ciphers without an IV - cipher_no_iv() +

To be used with:

-

To dynamically check availability, check that the name in the Cipher and Mode column is present in the - list returned by crypto:supports(ciphers). + + crypto_one_time/4 + crypto_init/3 + +

The ciphers are:

- Cipher and ModeKey length
[bytes]IV length
[bytes]Block size
[bytes] - aes_cbc 16, 24, 321616 - aes_cbc128161616 - aes_cbc256321616 - - aes_cfb8 16, 24, 3216any - - aes_ecb16, 24, 32 16 - - aes_ige256163216 - blowfish_cbc 4-56 8 8 - blowfish_cfb64 ≥1 8 any - blowfish_ecb≥1 8 - blowfish_ofb64≥18any - - des3_cbc
(=DES EDE3 CBC)[8,8,8]88 - des3_cfb
(=DES EDE3 CFB)[8,8,8]8any - - des_cbc88 8 - des_cfb88any - des_ecb8 8 - des_ede3
(=DES EDE3 CBC)[8,8,8]88 - rc2_cbc≥188 - Block cipher key lengths + + Cipher and Mode + Key length
[bytes] + Block size
[bytes] + + aes_128_ecb 16 16 + aes_192_ecb 24 16 + aes_256_ecb 32 16 + blowfish_ecb 16  8 + des_ecb  8  8 + rc4 16  1 + Ciphers without IV
- AEAD Ciphers -

To be used in block_encrypt/4 and - block_decrypt/4. + Ciphers with an IV - cipher_iv() +

To be used with:

-

To dynamically check availability, check that the name in the Cipher and Mode column is present in the - list returned by crypto:supports(ciphers). + + crypto_one_time/5 + crypto_init/4 + crypto_dyn_iv_init/3 + +

The ciphers are:

- Cipher and ModeKey length
[bytes]IV length
[bytes]AAD length
[bytes]Tag length
[bytes]Block size
[bytes]Supported with
OpenSSL versions - aes_ccm 16,24,32 7-13 any even 4-16
default: 12 any≥1.1.0 - aes_gcm 16,24,32 ≥1 any 1-16
default: 16 any≥1.1.0 - chacha20_poly130532 1-16 any 16 any≥1.1.0 - AEAD cipher key lengths + + Cipher and Mode + Key length
[bytes] + IV length
[bytes] + Block size
[bytes] + Limited to
OpenSSL versions + + aes_128_cbc 16 16 16 + aes_192_cbc 24 16 16 + aes_256_cbc 32 16 16 + aes_128_cfb8 16 16  1 + aes_192_cfb8 24 16  1 + aes_256_cfb8 32 16  1 + aes_128_cfb12816 16  1 + aes_192_cfb12824 16  1 + aes_256_cfb12832 16  1 + aes_128_ctr 16 16  1 + aes_192_ctr 24 16  1 + aes_256_ctr 32 16  1 + aes_ige256 16 32 16 + blowfish_cbc 16  8  8 + blowfish_cfb6416  8  1 + blowfish_ofb6416  8  1 + chacha20 32 16  1 ≥1.1.0d + des_cbc  8  8  8 + des_ede3_cbc 24  8  8 + des_cfb  8  8  1 + des_ede3_cfb 24  8  1 + rc2_cbc 16  8  8 + Ciphers with IV
- Stream Ciphers -

To be used in stream_init/2 and - stream_init/3. + Ciphers with AEAD - cipher_aead() +

To be used with:

-

To dynamically check availability, check that the name in the Cipher and Mode column is present in the - list returned by crypto:supports(ciphers). + + crypto_one_time_aead/6 + crypto_one_time_aead/7 + +

The ciphers are:

- Cipher and ModeKey length
[bytes]IV length
[bytes]Supported with
OpenSSL versions - aes_ctr16, 24, 3216≥1.0.1 - rc4≥1 all - Stream cipher key lengths + + Cipher and Mode + Key length
[bytes] + IV length
[bytes] + AAD length
[bytes] + Tag length
[bytes] + Block size
[bytes] + Limited to
OpenSSL versions + + aes_128_ccm 16 7-13 any even 4-16
default: 12 any≥1.0.1 + aes_192_ccm 24 7-13 any even 4-16
default: 12 any≥1.0.1 + aes_256_ccm 32 7-13 any even 4-16
default: 12 any≥1.0.1 + + aes_128_gcm 16 ≥1 any 1-16
default: 16 any≥1.0.1 + aes_192_gcm 24 ≥1 any 1-16
default: 16 any≥1.0.1 + aes_256_gcm 32 ≥1 any 1-16
default: 16 any≥1.0.1 + + chacha20_poly130532 1-16 any 16 any≥1.1.0 + AEAD ciphers
+
Message Authentication Codes (MACs)

To be used in mac/4 and @@ -129,26 +177,23 @@ list returned by crypto:supports(ciphers).

- Cipher and ModeKey length
[bytes]Max Mac Length
[bytes] - aes_cbc 16, 24, 3216 - aes_cbc1281616 - aes_cbc2563216 - - aes_cfb8 161 - - blowfish_cbc 4-56 8 - blowfish_cfb64 ≥1 1 - blowfish_ecb≥1 8 - blowfish_ofb64≥1 1 - - des3_cbc
(=DES EDE3 CBC)[8,8,8]8 - des3_cfb
(=DES EDE3 CFB)[8,8,8]1 - - des_cbc88 - - des_cfb81 - des_ecb81 - rc2_cbc≥18 + + Cipher and Mode + Key length
[bytes] + Max Mac Length
(= default length)
[bytes] + + aes_128_cbc 16 16 + aes_192_cbc 24 16 + aes_256_cbc 32 16 + aes_128_ecb 16 16 + aes_192_ecb 24 16 + aes_256_ecb 32 16 + blowfish_cbc 16  8 + blowfish_ecb 16  8 + des_cbc  8  8 + des_ecb  8  8 + des_ede3_cbc 24  8 + rc2_cbc 16  8CMAC cipher key lengths
@@ -158,8 +203,34 @@

Available in all OpenSSL compatible with Erlang CRYPTO if not disabled by configuration.

To dynamically check availability, check that the name hmac is present in the - list returned by crypto:supports(macs). + list returned by crypto:supports(macs) and + that the hash name is present in the + list returned by crypto:supports(hashs).

+ + + + Hash + Max Mac Length
(= default length)
[bytes] + + sha 20 + sha224 28 + sha256 32 + sha384 48 + sha512 64 + sha3_224 28 + sha3_256 32 + sha3_384 48 + sha3_512 64 + blake2b 64 + blake2s 32 + md4 16 + md5 16 + ripemd160 20 + HMAC output sizes +
+ +
@@ -169,6 +240,8 @@

To dynamically check availability, check that the name poly1305 is present in the list returned by crypto:supports(macs).

+

The poly1305 mac wants an 32 bytes key and produces a 16 byte MAC by default. +

@@ -183,14 +256,14 @@ Type Names - Supported with
OpenSSL versions + Limitated to
OpenSSL versions - SHA1shaall - SHA2sha224, sha256, sha384, sha512all + SHA1sha + SHA2sha224, sha256, sha384, sha512SHA3sha3_224, sha3_256, sha3_384, sha3_512≥1.1.1 - MD4md4all - MD5md5all - RIPEMDripemd160all + MD4md4 + MD5md5 + RIPEMDripemd160
diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 26fbfc166e..8988a18482 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -814,10 +814,16 @@

SubType depends on the MAC Type:

- For hmac it is a hash algorithm - For cmac it is a cipher suitable for cmac + For hmac it is a hash algorithm, see + Algorithm Details in the User's Guide. + + For cmac it is a cipher suitable for cmac, see + Algorithm Details in the User's Guide. + For poly1305 it should be set to undefined or the - mac/3 function could be used instead. + mac/2 function could be used instead, see + Algorithm Details in the User's Guide. +

Key is the authentication key with a length according to the @@ -832,6 +838,9 @@

The Mac result will have a default length depending on the Type and SubType. To set a shorter length, use macN/4 or macN/5 instead. + The default length is documented in + Algorithm Details + in the User's Guide.

@@ -857,6 +866,10 @@ bytes returned from the underlying hash, the returned hash will have that shorter length instead.

+

The max MacLength is documented in + Algorithm Details + in the User's Guide. +

@@ -881,10 +894,16 @@

SubType depends on the MAC Type:

- For hmac it is a hash algorithm - For cmac it is a cipher suitable for cmac + For hmac it is a hash algorithm, see + Algorithm Details in the User's Guide. + + For cmac it is a cipher suitable for cmac, see + Algorithm Details in the User's Guide. + For poly1305 it should be set to undefined or the - mac/2 function could be used instead. + mac/2 function could be used instead, see + Algorithm Details in the User's Guide. +

Key is the authentication key with a length according to the @@ -933,6 +952,9 @@ a default length depending on the Type and SubType in the mac_init/2,3 call. To set a shorter length, use mac_finalN/2 instead. + The default length is documented in + Algorithm Details + in the User's Guide.

@@ -948,6 +970,10 @@ bytes returned from the underlying hash, the returned hash will have that shorter length instead.

+

The max MacLength is documented in + Algorithm Details + in the User's Guide. +

-- cgit v1.2.3