diff options
| -rw-r--r-- | lib/crypto/doc/src/crypto.xml | 16 | ||||
| -rw-r--r-- | lib/crypto/doc/src/new_api.xml | 81 |
2 files changed, 68 insertions, 29 deletions
diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 751cf9d1fc..d1d1252f29 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -678,7 +678,8 @@ </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>See <seealso marker="crypto:new_api#examples-of-crypto_init-4-and-crypto_update-2"> + examples in the User's Guide.</seealso> </p> </desc> </func> @@ -696,7 +697,8 @@ 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>See <seealso marker="crypto:new_api#examples-of-crypto_init-4-and-crypto_update-2"> + examples in the User's Guide.</seealso> </p> </desc> </func> @@ -712,8 +714,6 @@ </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> </desc> </func> @@ -726,8 +726,6 @@ The <c>State</c> should be created with <seealso marker="crypto#crypto_dyn_iv_init/3">crypto_dyn_iv_init/3</seealso>. </p> - <p>See <seealso marker="crypto:new_api#the-new-api">examples in the User's Guide.</seealso> - </p> </desc> </func> @@ -744,11 +742,11 @@ <fsummary>Do a complete encrypt or decrypt of the full text</fsummary> <desc> <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. + Do a complete encrypt or decrypt of the full text in the argument <c>Data</c>. </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>See <seealso marker="crypto:new_api#example-of-crypto_one_time-5">examples in the User's Guide.</seealso> </p> </desc> </func> @@ -768,7 +766,7 @@ <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>See <seealso marker="crypto:new_api#example-of-crypto_one_time_aead-6">examples in the User's Guide.</seealso> </p> </desc> </func> diff --git a/lib/crypto/doc/src/new_api.xml b/lib/crypto/doc/src/new_api.xml index 58ace97554..bd2334ac9f 100644 --- a/lib/crypto/doc/src/new_api.xml +++ b/lib/crypto/doc/src/new_api.xml @@ -59,9 +59,9 @@ <item><seealso marker="crypto#stream_init-2">stream_init/3</seealso></item> <item><seealso marker="crypto#stream_encrypt-2">stream_encrypt/2</seealso></item> <item><seealso marker="crypto#stream_decrypt-2">stream_decrypt/2</seealso></item> - <item><seealso marker="crypto#supports-0">suppports/0</seealso></item> + <item><seealso marker="crypto#supports-0">supports/0</seealso></item> </list> - <p>They are not deprecated for now, but may be in a future. + <p>They are not deprecated for now, but may be in a future release. </p> </section> @@ -76,7 +76,8 @@ <item><seealso marker="crypto#crypto_one_time_aead/7">crypto_one_time_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, + 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. </p> <p>The <c>crypto_one_time_aead</c> functions are for the ciphers of mode <c>ccm</c> or @@ -114,29 +115,39 @@ <section> <title>Examples of crypto_init/4 and crypto_update/2</title> - <p>Encrypting two blocks:</p> + <p>The functions <seealso marker="crypto#crypto_init/4">crypto_init/4</seealso> + and <seealso marker="crypto#crypto_update/2">crypto_update/2</seealso> are intended + to be used for encrypting or decrypting a sequence of blocks. First one call of + <c>crypto_init/4</c> initialises the crypto context. One or more calls <c>crypto_update/2</c> + does the actual encryption or decryption for each block. + </p> + <p>This example shows first the encryption of two blocks and then decryptions of the cipher + text, but divided into three blocks just to show that it is possible to divide the plain text and + cipher text differently for some ciphers:</p> <code type="erl"> 1> crypto:start(). ok 2> Key = <<1:128>>. - 2> IV = <<0:128>>. - 2> StateEnc = crypto:crypto_init(aes_128_ctr, Key, IV, true). % encrypt -> true + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>> + 3> IV = <<0:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0>> + 4> StateEnc = crypto:crypto_init(aes_128_ctr, Key, IV, true). % encrypt -> true #Ref<0.3768901617.1128660993.124047> - 3> crypto:crypto_update(StateEnc, <<"First bytes">>). + 5> crypto:crypto_update(StateEnc, <<"First bytes">>). <<67,44,216,166,25,130,203,5,66,6,162>> - 4> crypto:crypto_update(StateEnc, <<"Second bytes">>). + 6> crypto:crypto_update(StateEnc, <<"Second bytes">>). <<16,79,94,115,234,197,94,253,16,144,151,41>> - 5> - 5> StateDec = crypto:crypto_init(aes_128_ctr, Key, IV, false). % decrypt -> false + 7> + 7> StateDec = crypto:crypto_init(aes_128_ctr, Key, IV, false). % decrypt -> false #Ref<0.3768901617.1128660994.124255> - 6> crypto:crypto_update(StateDec, <<67,44,216,166,25,130,203>>). + 8> crypto:crypto_update(StateDec, <<67,44,216,166,25,130,203>>). <<"First b">> - 7> crypto:crypto_update(StateDec, <<5,66,6,162,16,79,94,115,234,197, - 94,253,16,144,151>>). + 9> crypto:crypto_update(StateDec, <<5,66,6,162,16,79,94,115,234,197, + 94,253,16,144,151>>). <<"ytesSecond byte">> - 8> crypto:crypto_update(StateDec, <<41>>). + 10> crypto:crypto_update(StateDec, <<41>>). <<"s">> - 9> + 11> </code> <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>. @@ -163,21 +174,51 @@ <title>Example of crypto_one_time/5</title> <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>: + but now with one call to <seealso marker="crypto#crypto_one_time/5">crypto_one_time/5</seealso>: </p> <code> - 2> Key = <<1:128>>. + 1> Key = <<1:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>> 2> IV = <<0:128>>. - 2> Txt = [<<"First bytes">>,<<"Second bytes">>], - 2> crypto:crypto_one_time(aes_128_ctr, Key, IV, Txt, true). + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0>> + 3> Txt = [<<"First bytes">>,<<"Second bytes">>]. + [<<"First bytes">>,<<"Second bytes">>] + 4> 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, 197,94,253,16,144,151,41>> - 3> + 5> </code> <p>The <c>[<<"First bytes">>,<<"Second bytes">>]</c> could of course have been one single binary: <c><<"First bytesSecond bytes">></c>. </p> </section> + + <section> + <title>Example of crypto_one_time_aead/6</title> + <p>The same example as in the + <seealso marker="#example-of-crypto_one_time-5">previous section</seealso>, + but now with one call to <seealso marker="crypto#crypto_one_time_aead/6">crypto_one_time_aead/6</seealso>: + </p> + <code> + 1> Key = <<1:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1>> + 2> IV = <<0:128>>. + <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0>> + 3> Txt = [<<"First bytes">>,<<"Second bytes">>]. + [<<"First bytes">>,<<"Second bytes">>] + 4> AAD = <<"Some bytes">>. + <<"Some bytes">> + 5> crypto:crypto_one_time_aead(aes_128_gcm, Key, IV, Txt, AAD, true). + {<<240,130,38,96,130,241,189,52,3,190,179,213,132,1,72, + 192,103,176,90,104,15,71,158>>, + <<131,47,45,91,142,85,9,244,21,141,214,71,31,135,2,155>>} + 9> + </code> + <p>The <c>[<<"First bytes">>,<<"Second bytes">>]</c> could of course have been one + single binary: <c><<"First bytesSecond bytes">></c>. + </p> + </section> + </section> <section> |