From 6a74988149e362566ebd5dc79e39edcb48d564a3 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Tue, 9 Apr 2019 12:18:28 +0200 Subject: crypto: Doc review comments This reverts commit c207d2438017d15e32f47f5ff7168759b3d123fc. --- lib/crypto/doc/src/crypto.xml | 44 +++++++++++++++++++++++++----------------- lib/crypto/doc/src/new_api.xml | 36 ++++++++++++++++++---------------- 2 files changed, 45 insertions(+), 35 deletions(-) diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 14efc5c6f6..db53eed738 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -671,11 +671,12 @@ Initializes a series of encryptions or decryptions

Part of the new API. - Initializes a series of encryptions or decryptions. + Initializes a series of encryptions or decryptions and creates an internal state + with a reference that is returned. The actual encryption or decryption is done by crypto_update/2.

-

For encryption, set the EncryptFlag to true. +

For encryption, set the EncryptFlag to true. For decryption, set it to false.

See examples in the User's Guide.

@@ -683,15 +684,17 @@ - - Initializes a series of encryptions or decryptions where the IV is provided later + + Do an actual crypto operation on a part of the full text

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. + It does an actual crypto operation on a part of the full text. If the part is less + than a number of full blocks, only the full blocks (possibly none) are encrypted + or decrypted and the remaining bytes are saved to the next crypto_update operation. + The State should be created with + crypto_init/3 + or + crypto_init/4.

See examples in the User's Guide.

@@ -699,15 +702,15 @@ - - Do an actual crypto operation on a part of the full text + + Initializes a series of encryptions or decryptions where the IV is provided later

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. + 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. For decryption, set it to false.

See examples in the User's Guide.

@@ -743,7 +746,7 @@

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

-

For encryption, set the EncryptFlag to true. +

For encryption, set the EncryptFlag to true. For decryption, set it to false.

See examples in the User's Guide.

@@ -758,7 +761,12 @@

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

For encryption, set the EncryptFlag to true and set the TagOrTagLength + to the wanted size of the tag, that is, the tag length. If the default length is wanted, the + crypto_aead/6 form may be used. +

+

For decryption, set the EncryptFlag to false and put the tag to be checked + in the argument TagOrTagLength.

See examples in the User's Guide.

diff --git a/lib/crypto/doc/src/new_api.xml b/lib/crypto/doc/src/new_api.xml index 66eeefb692..e5e108d973 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 was wanted 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. @@ -66,7 +66,7 @@

The new API -

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

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

crypto_one_time/4 @@ -74,18 +74,23 @@ crypto_aead/6 crypto_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 data is encrypted or decrypted, + the crypto state is de-allocated and the result of the crypto operation is returned. +

The crypto_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 parts are handled - one by one but in sequence, the functions are: +

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 a cipher operation and one or more calls of +

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.

@@ -105,8 +110,8 @@ 1> crypto:start(). ok - 2> Key = <<1:128>>, - 2> IV = <<0:128>>, + 2> Key = <<1:128>>. + 2> IV = <<0:128>>. 2> StateEnc = crypto:crypto_init(aes_128_ctr, Key, IV, true). % encrypt -> true #Ref<0.3768901617.1128660993.124047> 3> crypto:crypto_update(StateEnc, <<"First bytes">>). @@ -125,8 +130,8 @@ <<"s">> 9> -

Note that the data that the StateEnc and StateDec references are destructivly - updated by the calls to crypto_update/2. +

Note that the internal data that the StateEnc and StateDec references are + destructivly updated by the calls to crypto_update/2. This is to gain time in the calls of the nifs interfacing the cryptolib. In a loop where the state is saved in the loop's state, it also saves one update of the loop state per crypto operation.

@@ -135,7 +140,7 @@

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 @@ -144,20 +149,17 @@ loop(State) end. -

Note that the State is not updated. Such updates could be costly if the loop state - is a tuple or record with many elements. -

-
+
Example of crypto_one_time/5 -

The same eample as in the +

The same example as in the previous section, but now with one call to crypto_one_time/5:

- 2> Key = <<1:128>>, - 2> IV = <<0:128>>, + 2> Key = <<1:128>>. + 2> IV = <<0:128>>. 2> Txt = [<<"First bytes">>,<<"Second bytes">>], 2> crypto:crypto_one_time(aes_128_ctr, Key, IV, Txt, true). <<67,44,216,166,25,130,203,5,66,6,162,16,79,94,115,234, -- cgit v1.2.3