aboutsummaryrefslogtreecommitdiffstats
path: root/lib/crypto/doc
diff options
context:
space:
mode:
authorHans Nilsson <[email protected]>2019-04-09 12:18:28 +0200
committerHans Nilsson <[email protected]>2019-04-11 13:00:46 +0200
commit6a74988149e362566ebd5dc79e39edcb48d564a3 (patch)
treeeeae5757510440b77437b7d051008623ec1b9480 /lib/crypto/doc
parent647ef8a165f2d7d63b4a766bd51c753c4fc24a36 (diff)
downloadotp-6a74988149e362566ebd5dc79e39edcb48d564a3.tar.gz
otp-6a74988149e362566ebd5dc79e39edcb48d564a3.tar.bz2
otp-6a74988149e362566ebd5dc79e39edcb48d564a3.zip
crypto: Doc review comments
This reverts commit c207d2438017d15e32f47f5ff7168759b3d123fc.
Diffstat (limited to 'lib/crypto/doc')
-rw-r--r--lib/crypto/doc/src/crypto.xml44
-rw-r--r--lib/crypto/doc/src/new_api.xml36
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 @@
<fsummary>Initializes a series of encryptions or decryptions</fsummary>
<desc>
<p>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>.
- 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
<seealso marker="crypto#crypto_update/2">crypto_update/2</seealso>.
</p>
- <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>.
+ <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>. For decryption, set it to <c>false</c>.
</p>
<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
</p>
@@ -683,15 +684,17 @@
</func>
<func>
- <name name="crypto_init_dyn_iv" arity="3" since="OTP 22.0"/>
- <fsummary>Initializes a series of encryptions or decryptions where the IV is provided later</fsummary>
+ <name name="crypto_update" arity="2" since="OTP 22.0"/>
+ <fsummary>Do an actual crypto operation on a part of the full text</fsummary>
<desc>
<p>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>.
- Initializes a series of encryptions or decryptions where the IV is provided later.
- The actual encryption or decryption is done by
- <seealso marker="crypto#crypto_update_dyn_iv/3">crypto_update_dyn_iv/3</seealso>.
- </p>
- <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>.
+ 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 <c>crypto_update</c> operation.
+ The <c>State</c> should be created with
+ <seealso marker="crypto#crypto_init/3">crypto_init/3</seealso>
+ or
+ <seealso marker="crypto#crypto_init/4">crypto_init/4</seealso>.
</p>
<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
</p>
@@ -699,15 +702,15 @@
</func>
<func>
- <name name="crypto_update" arity="2" since="OTP 22.0"/>
- <fsummary>Do an actual crypto operation on a part of the full text</fsummary>
+ <name name="crypto_init_dyn_iv" arity="3" since="OTP 22.0"/>
+ <fsummary>Initializes a series of encryptions or decryptions where the IV is provided later</fsummary>
<desc>
<p>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>.
- Do an actual crypto operation on a part of the full text.
- The <c>State</c> should be created with
- <seealso marker="crypto#crypto_init/3">crypto_init/3</seealso>
- or
- <seealso marker="crypto#crypto_init/4">crypto_init/4</seealso>.
+ Initializes a series of encryptions or decryptions where the IV is provided later.
+ The actual encryption or decryption is done by
+ <seealso marker="crypto#crypto_update_dyn_iv/3">crypto_update_dyn_iv/3</seealso>.
+ </p>
+ <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>. For decryption, set it to <c>false</c>.
</p>
<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
</p>
@@ -743,7 +746,7 @@
<p>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>.
Do a complete encrypt or decrypt of the full text.
</p>
- <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>.
+ <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>. For decryption, set it to <c>false</c>.
</p>
<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
</p>
@@ -758,7 +761,12 @@
<p>Part of the <seealso marker="crypto:new_api#the-new-api">new API</seealso>.
Do a complete encrypt or decrypt with an AEAD cipher of the full text.
</p>
- <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c>.
+ <p>For encryption, set the <c>EncryptFlag</c> to <c>true</c> and set the <c>TagOrTagLength</c>
+ to the wanted size of the tag, that is, the tag length. If the default length is wanted, the
+ <c>crypto_aead/6</c> form may be used.
+ </p>
+ <p>For decryption, set the <c>EncryptFlag</c> to <c>false</c> and put the tag to be checked
+ in the argument <c>TagOrTagLength</c>.
</p>
<p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso>
</p>
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.
</p>
<p>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.
</p>
<p>Therefore the old api (see next section) is kept for now but internally implemented with new primitives.
@@ -66,7 +66,7 @@
<section>
<title>The new API</title>
- <p>The new functions for encrypting or decrypting one single text in one binary are:
+ <p>The new functions for encrypting or decrypting one single binary are:
</p>
<list>
<item><seealso marker="crypto#crypto_one_time/4">crypto_one_time/4</seealso></item>
@@ -74,18 +74,23 @@
<item><seealso marker="crypto#crypto_aead/6">crypto_aead/6</seealso></item>
<item><seealso marker="crypto#crypto_aead/7">crypto_aead/7</seealso></item>
</list>
+ <p>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.
+ </p>
<p>The <c>crypto_aead</c> functions are for the ciphers of mode <c>ccm</c> or
<c>gcm</c>, and for the cipher <c>chacha20-poly1305</c>.
</p>
- <p>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:
+ <p>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:
</p>
<list>
<item><seealso marker="crypto#crypto_init/4">crypto_init/4</seealso></item>
<item><seealso marker="crypto#crypto_init/3">crypto_init/3</seealso></item>
<item><seealso marker="crypto#crypto_update/2">crypto_update/2</seealso></item>
</list>
- <p>The <c>crypto_init</c> initialies a cipher operation and one or more calls of
+ <p>The <c>crypto_init</c> initialies an internal cipher state, and one or more calls of
<c>crypto_update</c> does the acual encryption or decryption. Note that AEAD ciphers
can't be handled this way due to their nature.
</p>
@@ -105,8 +110,8 @@
<code type="erl">
1> crypto:start().
ok
- 2> Key = &lt;&lt;1:128>>,
- 2> IV = &lt;&lt;0:128>>,
+ 2> Key = &lt;&lt;1:128>>.
+ 2> IV = &lt;&lt;0:128>>.
2> StateEnc = crypto:crypto_init(aes_128_ctr, Key, IV, true). % encrypt -> true
#Ref&lt;0.3768901617.1128660993.124047>
3> crypto:crypto_update(StateEnc, &lt;&lt;"First bytes">>).
@@ -125,8 +130,8 @@
&lt;&lt;"s">>
9>
</code>
- <p>Note that the data that the <c>StateEnc</c> and <c>StateDec</c> references are destructivly
- updated by the calls to <seealso marker="crypto#crypto_update/2">crypto_update/2</seealso>.
+ <p>Note that the internal data that the <c>StateEnc</c> and <c>StateDec</c> references are
+ destructivly updated by the calls to <seealso marker="crypto#crypto_update/2">crypto_update/2</seealso>.
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.
</p>
@@ -135,7 +140,7 @@
</p>
<code type="erl">
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.
</code>
- <p>Note that the <c>State</c> is not updated. Such updates could be costly if the loop state
- is a tuple or record with many elements.
- </p>
- </section>
+ </section>
<section>
<title>Example of crypto_one_time/5</title>
- <p>The same eample as in the
+ <p>The same example as in the
<seealso marker="#examples-of-crypto_init-4-and-crypto_update-2">previous section</seealso>,
but now with one call to <c>crypto_one_time/5</c>:
</p>
<code>
- 2> Key = &lt;&lt;1:128>>,
- 2> IV = &lt;&lt;0:128>>,
+ 2> Key = &lt;&lt;1:128>>.
+ 2> IV = &lt;&lt;0:128>>.
2> Txt = [&lt;&lt;"First bytes">>,&lt;&lt;"Second bytes">>],
2> crypto:crypto_one_time(aes_128_ctr, Key, IV, Txt, true).
&lt;&lt;67,44,216,166,25,130,203,5,66,6,162,16,79,94,115,234,