From 16788a3c10298a6a68b2e1e6362be05780f910cf Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Wed, 27 Mar 2019 14:02:53 +0100 Subject: crypto: User's Guide and Reference Manual for the new api --- lib/crypto/doc/src/crypto.xml | 501 +++++++++++++++++++++++++++++------------- 1 file changed, 345 insertions(+), 156 deletions(-) (limited to 'lib/crypto/doc/src/crypto.xml') diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 8a4fad67de..14efc5c6f6 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -42,7 +42,7 @@ SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions [FIPS PUB 202] - + BLAKE2 @@ -190,70 +190,101 @@ - Ciphers + Ciphers, new API - - -

Ciphers known byt the CRYPTO application. Note that this list might be reduced if the - underlying libcrypto does not support all of them.

 - - - + -

Stream ciphers for - stream_init/3 and - stream_init/2 . -

+ + + + + + + + + + +

Ciphers known by the CRYPTO application when using the + new API.

+

Note that this list might be reduced if the underlying libcrypto does not support all of them.

 + Ciphers, old API + + + + + + + + + + + + + + + + + + + + - + + + + -

Block ciphers with initialization vector for - block_encrypt/4 and - block_decrypt/4 . -

- - - + -

Names that are replaced by more common names. They may deprecated in futer releases.

-

des3_cbc and des_ede3 should be replaced by des_ede3_cbc

-

des_ede3_cbf, des3_cbf and des3_cfb should be replaced by des_ede3_cfb.

-

aes_cbc128 should be replaced by aes_128_cbc.

-

aes_cbc256 should be replaced by aes_256_cbc.

 - - -

Block ciphers without initialization vector for - block_encrypt/3 and - block_decrypt/3 . -

+

Ciphers known by the CRYPTO application when using the + old API.

+

Note that this list might be reduced if the underlying libcrypto does not support all of them.

 - + + + + + + -

Ciphers with simultaneous MAC-calculation or MAC-checking. - block_encrypt/4 and - block_decrypt/4 . + + + + + + + + + + +

Alternative, old names of ciphers known by the CRYPTO application when using the + old API. + See Retired cipher names for names to + use instead to be prepared for an easy convertion to the + new API.

+

Note that this list might be reduced if the underlying libcrypto does not support all of them.

 @@ -547,6 +578,7 @@ +

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

@@ -575,117 +607,171 @@

This is a more developed variant of the older run_time_error().

+

The exception is:

+ 
+	  {Tag, {C_FileName,LineNumber}, Description}
+
+	   Tag = badarg | notsup | error
+	   C_FileName = string()
+	   LineNumber = integer()
+	   Description = string()
+
+

It is like the older type an exception of the error 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".

-

The exceptions are:

+

The exception tags are:

- {badarg, Description::string()} + badarg

Signifies that one or more arguments are of wrong data type or are otherwise badly formed.

 - {notsup, Description::string()} + notsup

Signifies that the algorithm is known but is not supported by current underlying libcrypto or explicitly disabled when building that one.

 - {error, Description::string()} + error

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.

 +

To catch the exception, use for example:

+ + try crypto:crypto_init(Ciph, Key, IV, true) + catch + error:{Tag, {C_FileName,LineNumber}, Description} -> + do_something(......) + ..... + end + +
+ New API +
+ - - Encrypt PlainText according to Type block cipher + + Initializes a series of encryptions or decryptions -

Encrypt PlainText according to Type block cipher.

-

May raise exception error:notsup in case the chosen Type - is not supported by the underlying libcrypto implementation.

-

For keylengths and blocksizes see the - User's Guide. +

As crypto_init/4 but for ciphers without IVs.

+ + + + + + Initializes a series of encryptions or decryptions + +

Part of the new API. + Initializes a series of encryptions or decryptions. + The actual encryption or decryption is done by + crypto_update/2. +

+

For encryption, set the EncryptFlag to true. +

+

See examples in the User's Guide.

- - Decrypt CipherText according to Type block cipher + + Initializes a series of encryptions or decryptions where the IV is provided later -

Decrypt CipherText according to Type block cipher.

-

May raise exception error:notsup in case the chosen Type - is not supported by the underlying libcrypto implementation.

-

For keylengths and blocksizes see the - User's Guide. +

Part of the new API. + Initializes a series of encryptions or decryptions where the IV is provided later. + The actual encryption or decryption is done by + crypto_update_dyn_iv/3. +

+

For encryption, set the EncryptFlag to true. +

+

See examples in the User's Guide.

- block_encrypt(Type, Key, Ivec, PlainText) -> CipherText | Error - block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText, CipherTag} | Error - block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText, TagLength}) -> {CipherText, CipherTag} | Error - Encrypt PlainText according to Type block cipher - - Type = block_cipher_iv() - AeadType = aead_cipher() - Key = key() | des3_key() - PlainText = iodata() - AAD = IVec = CipherText = CipherTag = binary() - TagLength = 1..16 - Error = run_time_error() - + + Do an actual crypto operation on a part of the full text -

Encrypt PlainText according to Type block cipher. - IVec is an arbitrary initializing vector.

-

In AEAD (Authenticated Encryption with Associated Data) mode, encrypt - PlainTextaccording to Type block cipher and calculate - CipherTag that also authenticates the AAD (Associated Authenticated Data).

-

May raise exception error:notsup in case the chosen Type - is not supported by the underlying libcrypto implementation.

-

For keylengths, iv-sizes and blocksizes see the - User's Guide. +

Part of the new API. + Do an actual crypto operation on a part of the full text. + The State should be created with + crypto_init/3 + or + crypto_init/4. +

+

See examples in the User's Guide.

- block_decrypt(Type, Key, Ivec, CipherText) -> PlainText | Error - block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) -> PlainText | Error - Decrypt CipherText according to Type block cipher - - Type = block_cipher_iv() - AeadType = aead_cipher() - Key = key() | des3_key() - PlainText = iodata() - AAD = IVec = CipherText = CipherTag = binary() - Error = BadTag | run_time_error() - BadTag = error - + + Do an actual crypto operation on a part of the full text and the IV is supplied for each part -

Decrypt CipherText according to Type block cipher. - IVec is an arbitrary initializing vector.

-

In AEAD (Authenticated Encryption with Associated Data) mode, decrypt - CipherTextaccording to Type block cipher and check the authenticity - the PlainText and AAD (Associated Authenticated Data) using the - CipherTag. May return error if the decryption or validation fail's

-

May raise exception error:notsup in case the chosen Type - is not supported by the underlying libcrypto implementation.

-

For keylengths, iv-sizes and blocksizes see the - User's Guide. +

Part of the new API. + Do an actual crypto operation on a part of the full text and the IV is supplied for each part. + The State should be created with + crypto_init_dyn_iv/3. +

+

See examples in the User's Guide.

- + + + Do a complete encrypt or decrypt of the full text + +

As crypto_one_time/5 but for ciphers without IVs.

+ + + + + + Do a complete encrypt or decrypt of the full text + +

Part of the new API. + Do a complete encrypt or decrypt of the full text. +

+

For encryption, set the EncryptFlag to true. +

+

See examples in the User's Guide. +

+ + + + + + + Do a complete encrypt or decrypt with an AEAD cipher of the full text + +

Part of the new API. + Do a complete encrypt or decrypt with an AEAD cipher of the full text. +

+

For encryption, set the EncryptFlag to true. +

+

See examples in the User's Guide. +

+ + + + +
+ API kept from previous versions +
+ + + Convert binary representation, of an integer, to an Erlang integer. @@ -928,7 +1014,7 @@ cipher algorithm in question.

-

The ciphers aes_cbc, aes_cfb8, aes_cfb128, aes_ctr, +

The ciphers aes_cbc, aes_cfb8, aes_cfb128, aes_ctr, aes_ecb, aes_gcm and aes_ccm has no keylength in the Type as opposed to for example aes_128_ctr. They adapt to the length of the key provided in the encrypt and decrypt function. Therefor it is impossible to return a valid keylength @@ -1094,7 +1180,7 @@ rand_seed_s/0.

- When using the state object from this function the + When using the state object from this function the rand functions using it may raise exception error:low_entropy in case the random generator failed due to lack of secure "randomness". @@ -1120,7 +1206,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ rand:seed_s/1.

- When using the state object from this function the + When using the state object from this function the rand functions using it may raise exception error:low_entropy in case the random generator failed due to lack of secure "randomness". @@ -1129,7 +1215,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[

The state returned from this function cannot be used to get a reproducable random sequence as from - the other + the other rand functions, since reproducability does not match cryptographically safe. @@ -1160,7 +1246,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ rand_seed_alg_s/1.

- When using the state object from this function the + When using the state object from this function the rand functions using it may raise exception error:low_entropy in case the random generator failed due to lack of secure "randomness". @@ -1227,7 +1313,7 @@ FloatValue = rand:uniform(). % again of 56 bits that makes calculations fast on 64 bit machines.

- When using the state object from this function the + When using the state object from this function the rand functions using it may raise exception error:low_entropy in case the random generator failed due to lack of secure "randomness". @@ -1248,7 +1334,7 @@ FloatValue = rand:uniform(). % again

The state returned from this function cannot be used to get a reproducable random sequence as from - the other + the other rand functions, since reproducability does not match cryptographically safe. @@ -1331,56 +1417,6 @@ FloatValue = rand:uniform(). % again - - - - -

Initializes the state for use in RC4 stream encryption - stream_encrypt and - stream_decrypt

-

For keylengths see the - User's Guide. -

- - - - - - - -

Initializes the state for use in streaming AES encryption using Counter mode (CTR). - Key is the AES key and must be either 128, 192, or 256 bits long. IVec is - an arbitrary initializing vector of 128 bits (16 bytes). This state is for use with - stream_encrypt and - stream_decrypt.

-

For keylengths and iv-sizes see the - User's Guide. -

- - - - - - - -

Encrypts PlainText according to the stream cipher Type specified in stream_init/3. - Text can be any number of bytes. The initial State is created using - stream_init. - NewState must be passed into the next call to stream_encrypt.

- - - - - - - -

Decrypts CipherText according to the stream cipher Type specified in stream_init/3. - PlainText can be any number of bytes. The initial State is created using - stream_init. - NewState must be passed into the next call to stream_decrypt.

- - - Provide a list of available crypto algorithms. @@ -1440,6 +1476,12 @@ FloatValue = rand:uniform(). % again + +
+ Engine API +
+ + @@ -1752,5 +1794,152 @@ FloatValue = rand:uniform(). % again +
+ Old API +
+ + + + + Encrypt PlainText according to Type block cipher + +

Don't use this function for new programs! Use the-new-api.

 +

Encrypt PlainText according to Type block cipher.

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

+

For keylengths and blocksizes see the + User's Guide. +

+ + + + + + Decrypt CipherText according to Type block cipher + +

Don't use this function for new programs! Use the new api.

 +

Decrypt CipherText according to Type block cipher.

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

+

For keylengths and blocksizes see the + User's Guide. +

+ + + + + block_encrypt(Type, Key, Ivec, PlainText) -> CipherText | Error + block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText, CipherTag} | Error + block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText, TagLength}) -> {CipherText, CipherTag} | Error + Encrypt PlainText according to Type block cipher + + Type = block_cipher_with_iv() + AeadType = aead_cipher() + Key = key() | des3_key() + PlainText = iodata() + AAD = IVec = CipherText = CipherTag = binary() + TagLength = 1..16 + Error = run_time_error() + + +

Don't use this function for new programs! Use the new api.

 +

Encrypt PlainText according to Type block cipher. + IVec is an arbitrary initializing vector.

+

In AEAD (Authenticated Encryption with Associated Data) mode, encrypt + PlainTextaccording to Type block cipher and calculate + CipherTag that also authenticates the AAD (Associated Authenticated Data).

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

+

For keylengths, iv-sizes and blocksizes see the + User's Guide. +

+ + + + + block_decrypt(Type, Key, Ivec, CipherText) -> PlainText | Error + block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) -> PlainText | Error + Decrypt CipherText according to Type block cipher + + Type = block_cipher_with_iv() + AeadType = aead_cipher() + Key = key() | des3_key() + PlainText = iodata() + AAD = IVec = CipherText = CipherTag = binary() + Error = BadTag | run_time_error() + BadTag = error + + +

Don't use this function for new programs! Use the new api.

 +

Decrypt CipherText according to Type block cipher. + IVec is an arbitrary initializing vector.

+

In AEAD (Authenticated Encryption with Associated Data) mode, decrypt + CipherTextaccording to Type block cipher and check the authenticity + the PlainText and AAD (Associated Authenticated Data) using the + CipherTag. May return error if the decryption or validation fail's

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

+

For keylengths, iv-sizes and blocksizes see the + User's Guide. +

+ + + + + + + +

Don't use this function for new programs! Use the new api.

 +

Initializes the state for use in RC4 stream encryption + stream_encrypt and + stream_decrypt

+

For keylengths see the + User's Guide. +

+ + + + + + + +

Don't use this function for new programs! Use the new api.

 +

Initializes the state for use in streaming AES encryption using Counter mode (CTR). + Key is the AES key and must be either 128, 192, or 256 bits long. IVec is + an arbitrary initializing vector of 128 bits (16 bytes). This state is for use with + stream_encrypt and + stream_decrypt.

+

For keylengths and iv-sizes see the + User's Guide. +

+ + + + + + + +

Don't use this function for new programs! Use the new api.

 +

Encrypts PlainText according to the stream cipher Type specified in stream_init/3. + Text can be any number of bytes. The initial State is created using + stream_init. + NewState must be passed into the next call to stream_encrypt.

+ + + + + + + +

Don't use this function for new programs! Use the new api.

 +

Decrypts CipherText according to the stream cipher Type specified in stream_init/3. + PlainText can be any number of bytes. The initial State is created using + stream_init. + NewState must be passed into the next call to stream_decrypt.

+ + + + + -- cgit v1.2.3