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(-)
(limited to 'lib')
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 Mode | Key length [bytes] | IV length [bytes] | Block size [bytes] |
- aes_cbc | 16, 24, 32 | 16 | 16 |
- aes_cbc128 | 16 | 16 | 16 |
- aes_cbc256 | 32 | 16 | 16 |
-
- aes_cfb8 | 16, 24, 32 | 16 | any |
-
- aes_ecb | 16, 24, 32 | | 16 |
-
- aes_ige256 | 16 | 32 | 16 |
- blowfish_cbc | 4-56 | 8 | 8 |
- blowfish_cfb64 | ≥1 | 8 | any |
- blowfish_ecb | ≥1 | | 8 |
- blowfish_ofb64 | ≥1 | 8 | any |
-
- des3_cbc (=DES EDE3 CBC) | [8,8,8] | 8 | 8 |
- des3_cfb (=DES EDE3 CFB) | [8,8,8] | 8 | any |
-
- des_cbc | 8 | 8 | 8 |
- des_cfb | 8 | 8 | any |
- des_ecb | 8 | | 8 |
- des_ede3 (=DES EDE3 CBC) | [8,8,8] | 8 | 8 |
- rc2_cbc | ≥1 | 8 | 8 |
- 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 Mode | Key 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_poly1305 | 32 | 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_cfb128 | 16 | 16 | 1 | |
+ aes_192_cfb128 | 24 | 16 | 1 | |
+ aes_256_cfb128 | 32 | 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_cfb64 | 16 | 8 | 1 | |
+ blowfish_ofb64 | 16 | 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 Mode | Key length [bytes] | IV length [bytes] | Supported with OpenSSL versions |
- aes_ctr | 16, 24, 32 | 16 | ≥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_poly1305 | 32 | 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 Mode | Key length [bytes] | Max Mac Length [bytes] |
- aes_cbc | 16, 24, 32 | 16 |
- aes_cbc128 | 16 | 16 |
- aes_cbc256 | 32 | 16 |
-
- aes_cfb8 | 16 | 1 |
-
- 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_cbc | 8 | 8 |
-
- des_cfb | 8 | 1 |
- des_ecb | 8 | 1 |
- rc2_cbc | ≥1 | 8 |
+
+ 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 | 8 |
CMAC 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 |
- SHA1 | sha | all |
- SHA2 | sha224, sha256, sha384, sha512 | all |
+ SHA1 | sha | |
+ SHA2 | sha224, sha256, sha384, sha512 | |
SHA3 | sha3_224, sha3_256, sha3_384, sha3_512 | ≥1.1.1 |
- MD4 | md4 | all |
- MD5 | md5 | all |
- RIPEMD | ripemd160 | all |
+ MD4 | md4 | |
+ MD5 | md5 | |
+ RIPEMD | ripemd160 | |
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