This chapter describes the new api to encryption and decryption.
The CRYPTO app has evolved during its lifetime. Since also the OpenSSL cryptolib has changed the API several times, there are parts of the CRYPTO app that uses a very old one internally and other parts that uses the latest one. The internal definitions of e.g cipher names was a bit hard 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 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.
The old functions - not recommended for new programs - are:
They are not deprecated for now, but may be in a future.
The new functions for encrypting or decrypting one single text in one binary are:
The
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:
The
Finally, 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:
An example of where those functions are needed, is when handling the TLS protocol.
Encrypting two blocks:
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
#Ref<0.3768901617.1128660993.124047>
3> crypto:crypto_update(StateEnc, <<"First bytes">>).
<<67,44,216,166,25,130,203,5,66,6,162>>
4> 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
#Ref<0.3768901617.1128660994.124255>
6> 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>>).
<<"ytesSecond byte">>
8> crypto:crypto_update(StateDec, <<41>>).
<<"s">>
9>
Note that the data that the
For example, a simple server receiving text parts to encrypt and send the result back to the
one who sent them (the
encode(Crypto, Key, IV) ->
crypto_loop(crypto:crypto_init(Crypto, Key, IV, true)).
crypto_loop(State) ->
receive
{Text, Requester} ->
Requester ! crypto:crypto_update(State, Text),
loop(State)
end.
Note that the
The same eample as in the
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,
197,94,253,16,144,151,41>>
3>
The
This table lists the retired cipher names in the first column and suggests names to replace them with in the second column.
The new names follows the OpenSSL libcrypto names. The format is ALGORITM_KEYSIZE_MODE.
Examples of algorithms are aes, chacha20 and des. The keysize is the number of bits and examples of the mode are cbc, ctr and gcm. The mode may be followed by a number depending 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 key length which improves the error checking in the lower levels of the crypto application.