From 511480bd35d03a52062ac340f49b5149d3dce507 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Wed, 5 Jun 2019 15:27:36 +0200 Subject: crypto: Documentation --- lib/crypto/doc/src/algorithm_details.xml | 63 ++---- lib/crypto/doc/src/crypto.xml | 360 ++++++++++++++++++++++++------- lib/crypto/doc/src/new_api.xml | 181 +++++++++++----- 3 files changed, 427 insertions(+), 177 deletions(-) (limited to 'lib/crypto') diff --git a/lib/crypto/doc/src/algorithm_details.xml b/lib/crypto/doc/src/algorithm_details.xml index 854bfbb4b1..85ae766c35 100644 --- a/lib/crypto/doc/src/algorithm_details.xml +++ b/lib/crypto/doc/src/algorithm_details.xml @@ -48,8 +48,7 @@

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

To dynamically check availability, check that the name in the Cipher and Mode column is present in the - list with the cipher tag in the return value of - crypto:supports(). + list returned by crypto:supports(ciphers).

Cipher and ModeKey length
[bytes]IV length
[bytes]Block size
[bytes] @@ -85,8 +84,7 @@ block_decrypt/4.

To dynamically check availability, check that the name in the Cipher and Mode column is present in the - list with the cipher tag in the return value of - crypto:supports(). + list returned by crypto:supports(ciphers).

Cipher and ModeKey length
[bytes]IV length
[bytes]AAD length
[bytes]Tag length
[bytes]Block size
[bytes]Supported with
OpenSSL versions @@ -103,8 +101,7 @@ stream_init/3.

To dynamically check availability, check that the name in the Cipher and Mode column is present in the - list with the cipher tag in the return value of - crypto:supports(). + list returned by crypto:supports(ciphers).

Cipher and ModeKey length
[bytes]IV length
[bytes]Supported with
OpenSSL versions @@ -117,20 +114,19 @@
Message Authentication Codes (MACs) +

To be used in mac/4 and + related functions. +

CMAC -

To be used in cmac/3 and - cmac/4. -

CMAC with the following ciphers are available with OpenSSL 1.0.1 or later if not disabled by configuration.

To dynamically check availability, check that the name cmac is present in the - list with the macs tag in the return value of - crypto:supports(). + list returned by crypto:supports(macs). Also check that the name in the Cipher and Mode column is present in the - list with the cipher tag in the return value. + list returned by crypto:supports(ciphers).

Cipher and ModeKey length
[bytes]Max Mac Length
[bytes] @@ -162,8 +158,7 @@

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 with the macs tag in the return value of - crypto:supports(). + list returned by crypto:supports(macs).

@@ -172,8 +167,7 @@

POLY1305 is available with OpenSSL 1.1.1 or later if not disabled by configuration.

To dynamically check availability, check that the name poly1305 is present in the - list with the macs tag in the return value of - crypto:supports(). + list returned by crypto:supports(macs).

@@ -183,11 +177,9 @@ Hash

To dynamically check availability, check that the wanted name in the Names column is present in the - list with the hashs tag in the return value of - crypto:supports(). + list returned by crypto:supports(hashs).

-
Type Names @@ -210,8 +202,7 @@ RSA

RSA is available with all OpenSSL versions compatible with Erlang CRYPTO if not disabled by configuration. To dynamically check availability, check that the atom rsa is present in the - list with the public_keys tag in the return value of - crypto:supports(). + list returned by crypto:supports(public_keys).

@@ -283,8 +274,7 @@ DSS

DSS is available with OpenSSL versions compatible with Erlang CRYPTO if not disabled by configuration. To dynamically check availability, check that the atom dss is present in the - list with the public_keys tag in the return value of - crypto:supports(). + list returned by crypto:supports(public_keys).

@@ -292,13 +282,11 @@ ECDSA

ECDSA is available with OpenSSL 0.9.8o or later if not disabled by configuration. To dynamically check availability, check that the atom ecdsa is present in the - list with the public_keys tag in the return value of - crypto:supports(). - If the atom ec_gf2m characteristic two field curves are available. + list returned by crypto:supports(public_keys). + If the atom ec_gf2m also is present, the characteristic two field curves are available.

-

The actual supported named curves could be checked by examining the list with the - curves tag in the return value of - crypto:supports(). +

The actual supported named curves could be checked by examining the + list returned by crypto:supports(curves).

@@ -306,13 +294,11 @@ EdDSA

EdDSA is available with OpenSSL 1.1.1 or later if not disabled by configuration. To dynamically check availability, check that the atom eddsa is present in the - list with the public_keys tag in the return value of - crypto:supports(). + list returned by crypto:supports(public_keys).

Support for the curves ed25519 and ed448 is implemented. The actual supported named curves could be checked by examining the list with the - curves tag in the return value of - crypto:supports(). + list returned by crypto:supports(curves).

@@ -321,8 +307,7 @@

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 dh is present in the - list with the public_keys tag in the return value of - crypto:supports(). + list returned by crypto:supports(public_keys).

@@ -330,17 +315,15 @@ Elliptic Curve Diffie-Hellman

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 ecdh is present in the - list with the public_keys tag in the return value of - crypto:supports(). + list returned by crypto:supports(public_keys).

The Edward curves x25519 and x448 are supported with OpenSSL 1.1.1 or later if not disabled by configuration.

-

The actual supported named curves could be checked by examining the list with the - curves tag in the return value of - crypto:supports(). +

The actual supported named curves could be checked by examining the + list returned by crypto:supports(curves).

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index d1d1252f29..26fbfc166e 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -301,6 +301,12 @@ + + + + + + @@ -324,6 +330,11 @@ + + + + +

The compatibility_only_hash() algorithms are recommended only for compatibility with existing applications.

@@ -575,10 +586,11 @@ Internal data types - - - + + + +

Contexts with an internal state that should not be manipulated but passed between function calls.

@@ -783,6 +795,161 @@ + + + + +

Short for mac(Type, undefined, Key, Data). +

+ + + + + + + +

Computes a MAC (Message Authentication Code) of type Type from Data. +

+ +

SubType depends on the MAC Type: +

+ + For hmac it is a hash algorithm + For cmac it is a cipher suitable for cmac + For poly1305 it should be set to undefined or the + mac/3 function could be used instead. + + +

Key is the authentication key with a length according to the + Type and SubType. + The key length could be found with the + hash_info/1 (hmac) for and + cipher_info/1 (cmac) + functions. For poly1305 the key length is 32 bytes. Note that + the cryptographic quality of the key is not checked. +

+ +

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. +

+ + + + + + + +

Short for macN(Type, undefined, Key, Data, MacLength). +

+ + + + + + + +

Computes a MAC (Message Authentication Code) + as mac/3 and mac/4 but + MacLength will limit the size of the resultant Mac to + at most MacLength bytes. + Note that if MacLength is greater than the actual number of + bytes returned from the underlying hash, the returned hash will have + that shorter length instead. +

+ + + + + + + +

Short for mac_init(Type, undefined, Key). +

+ + + + + + + +

Initializes the context for streaming MAC operations. +

+

Type determines which mac algorithm to use in the MAC operation. +

+ +

SubType depends on the MAC Type: +

+ + For hmac it is a hash algorithm + For cmac it is a cipher suitable for cmac + For poly1305 it should be set to undefined or the + mac/2 function could be used instead. + + +

Key is the authentication key with a length according to the + Type and SubType. + The key length could be found with the + hash_info/1 (hmac) for and + cipher_info/1 (cmac) + functions. For poly1305 the key length is 32 bytes. Note that + the cryptographic quality of the key is not checked. +

+ +

The returned State should be used in one or more subsequent calls to + mac_update/2. + The MAC value is finally returned by calling + mac_final/1 or + mac_finalN/2. +

+ +

See + examples in the User's Guide. +

+ + + + + + + +

Updates the MAC represented by State0 using the given Data which + could be of any length. +

+

The State0 is the State value originally from a MAC init function, that is + mac_init/2, + mac_init/3 or + a previous call of mac_update/2. + The value State0 is returned unchanged by the function as State. +

+ + + + + + + +

Finalizes the MAC operation referenced by State. The Mac result will have + 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. +

+ + + + + + + +

Finalizes the MAC operation referenced by State. +

+

Mac will be a binary with at most MacLength bytes. + Note that if MacLength is greater than the actual number of + bytes returned from the underlying hash, the returned hash will have + that shorter length instead. +

+ +
@@ -885,75 +1052,6 @@ - - - - - -

Computes a HMAC of type Type from Data using - Key as the authentication key.

MacLength - will limit the size of the resultant Mac.

- - - - - - - -

Initializes the context for streaming HMAC operations. Type determines - which hash function to use in the HMAC operation. Key is the authentication - key. The key can be any length.

- - - - - - - -

Updates the HMAC represented by Context using the given Data. Context - must have been generated using an HMAC init function (such as - hmac_init). Data can be any length. NewContext - must be passed into the next call to hmac_update - or to one of the functions hmac_final and - hmac_final_n -

-

Do not use a Context 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.

 - - - - - - - -

Finalizes the HMAC operation referenced by Context. The size of the resultant MAC is - determined by the type of hash function used to generate it.

- - - - - - - -

Finalizes the HMAC operation referenced by Context. HashLen must be greater than - zero. Mac will be a binary with at most HashLen 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 HashLen bytes.

- - - - - - - Calculates the Cipher-based Message Authentication Code. - -

Computes a CMAC of type Type from Data using - Key as the authentication key.

MacLength - will limit the size of the resultant Mac.

- - - Provides information about the FIPS operating status. @@ -1067,15 +1165,6 @@ - - - - -

Computes a POLY1305 message authentication code (Mac) from Data using - Key as the authentication key.

- - - Decrypts CipherText using the private Key. @@ -1961,6 +2050,115 @@ FloatValue = rand:uniform(). % again + + + + + +

Don't use this function for new programs! Use + mac/4 or + macN/5 in + the new api.

+ +

Computes a HMAC of type Type from Data using + Key as the authentication key.

MacLength + will limit the size of the resultant Mac.

+ + + + + + + +

Don't use this function for new programs! Use + mac_init/3 in + the new api.

+ +

Initializes the context for streaming HMAC operations. Type determines + which hash function to use in the HMAC operation. Key is the authentication + key. The key can be any length.

+ + + + + + + +

Don't use this function for new programs! Use + mac_update/2 in + the new api.

+ +

Updates the HMAC represented by Context using the given Data. Context + must have been generated using an HMAC init function (such as + hmac_init). Data can be any length. NewContext + must be passed into the next call to hmac_update + or to one of the functions hmac_final and + hmac_final_n +

+

Do not use a Context 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.

 + + + + + + + +

Don't use this function for new programs! Use + mac_final/1 in + the new api.

+ +

Finalizes the HMAC operation referenced by Context. The size of the resultant MAC is + determined by the type of hash function used to generate it.

+ + + + + + + +

Don't use this function for new programs! Use + mac_finalN/2 in + the new api.

+ +

Finalizes the HMAC operation referenced by Context. HashLen must be greater than + zero. Mac will be a binary with at most HashLen 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 HashLen bytes.

+ + + + + + + Calculates the Cipher-based Message Authentication Code. + +

Don't use this function for new programs! Use + mac/4 or + macN/5 in + the new api.

+ +

Computes a CMAC of type Type from Data using + Key as the authentication key.

MacLength + will limit the size of the resultant Mac.

+ + + + + + + +

Don't use this function for new programs! Use + mac/3 or + macN/4 in + the new api.

+ +

Computes a POLY1305 message authentication code (Mac) from Data using + Key as the authentication key.

+ + + diff --git a/lib/crypto/doc/src/new_api.xml b/lib/crypto/doc/src/new_api.xml index bd2334ac9f..aacf5e4f76 100644 --- a/lib/crypto/doc/src/new_api.xml +++ b/lib/crypto/doc/src/new_api.xml @@ -40,7 +40,7 @@ to maintain.

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 was wanted + backwards compatible, was not possible. Specially as more precision in the error messages is desired it could not be combined with the old standard.

Therefore the old api (see next section) is kept for now but internally implemented with new primitives. @@ -49,7 +49,7 @@

The old API -

The old functions - not recommended for new programs - are:

+

The old functions - not recommended for new programs - are for chipers:

block_encrypt/3 block_encrypt/4 @@ -59,60 +59,100 @@ stream_init/3 stream_encrypt/2 stream_decrypt/2 + +

for lists of supported algorithms:

+ supports/0 +

and for MACs (Message Authentication Codes):

+ + cmac/3 + cmac/4 + hmac/3 + hmac/4 + hmac_init/2 + hmac_update/2 + hmac_final/1 + hmac_final_n/2 + poly1305/2 +

They are not deprecated for now, but may be in a future release.

The new API -

The new functions for encrypting or decrypting one single binary are: -

- - crypto_one_time/4 - crypto_one_time/5 - crypto_one_time_aead/6 - crypto_one_time_aead/7 - -

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. -

-

The crypto_one_time_aead functions are for the ciphers of mode ccm or - gcm, and for the cipher chacha20-poly1305. -

-

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: -

- - crypto_init/4 - crypto_init/3 - crypto_update/2 - -

The crypto_init initialies an internal cipher state, and one or more calls of - crypto_update does the acual encryption or decryption. Note that AEAD ciphers - can't be handled this way due to their nature. -

-

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: -

- - crypto_dyn_iv_init/3 - crypto_dyn_iv_update/3 - -

An example of where those functions are needed, is when handling the TLS protocol.

-

For information about available algorithms, use: -

- - supports/1 - hash_info/1 - cipher_info/1 - +
+ Encryption and decryption +

The new functions for encrypting or decrypting one single binary are: +

+ + crypto_one_time/4 + crypto_one_time/5 + crypto_one_time_aead/6 + crypto_one_time_aead/7 + +

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. +

+

The crypto_one_time_aead functions are for the ciphers of mode ccm or + gcm, and for the cipher chacha20-poly1305. +

+

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: +

+ + crypto_init/4 + crypto_init/3 + crypto_update/2 + +

The crypto_init initialies an internal cipher state, and one or more calls of + crypto_update does the acual encryption or decryption. Note that AEAD ciphers + can't be handled this way due to their nature. +

+

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: +

+ + crypto_dyn_iv_init/3 + crypto_dyn_iv_update/3 + +

An example of where those functions are needed, is when handling the TLS protocol.

+

For information about available algorithms, use: +

+ + supports/1 + hash_info/1 + cipher_info/1 + +
+
+ MACs (Message Authentication Codes) +

The new functions for calculating a MAC of a single piece of text are:

+ + mac/3 + mac/4 + macN/4 + macN/5 + +

For calculating a MAC of a text divided in parts use:

+ + mac_init/2 + mac_init/3 + mac_update/2 + mac_final/1 + mac_finalN/2 + +
+
+ +
+ Examples of the new api
Examples of crypto_init/4 and crypto_update/2

The functions crypto_init/4 @@ -143,7 +183,7 @@ 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>>). + 94,253,16,144,151>>). <<"ytesSecond byte">> 10> crypto:crypto_update(StateDec, <<41>>). <<"s">> @@ -159,16 +199,16 @@

encode(Crypto, Key, IV) -> - crypto_loop(crypto:crypto_init(Crypto, Key, IV, true)). + crypto_loop(crypto:crypto_init(Crypto, Key, IV, true)). crypto_loop(State) -> - receive - {Text, Requester} -> - Requester ! crypto:crypto_update(State, Text), - loop(State) - end. + receive + {Text, Requester} -> + Requester ! crypto:crypto_update(State, Text), + loop(State) + end. -
+
Example of crypto_one_time/5 @@ -219,6 +259,35 @@

+
+ Example of mac_init mac_update and mac_final + + 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> + +

and compare the result with a single calculation just for this example:

+ + 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> + +
+
@@ -233,7 +302,7 @@ 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.

-

The old names had by time lost any common naming which the new names now introduces. The new names include +

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.

-- cgit v1.2.3