New and Old API

The new API

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

crypto_one_time/4 crypto_one_time/5 crypto_one_time_aead/6 crypto_one_time_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 single binary is encrypted or decrypted, the crypto state is de-allocated and the result of the crypto operation is returned.

The crypto_one_time_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 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 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.

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:

crypto_dyn_iv_init/3 crypto_dyn_iv_update/3

An example of where those functions are needed, is when handling the TLS protocol.

For information about available algorithms, use:

supports/1 hash_info/1 cipher_info/1

Examples of crypto_init/4 and crypto_update/2

The functions crypto_init/4 and crypto_update/2 are intended to be used for encrypting or decrypting a sequence of blocks. First one call of crypto_init/4 initialises the crypto context. One or more calls crypto_update/2 does the actual encryption or decryption for each block.

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:


	1> crypto:start().
	ok
	2> Key = <<1:128>>.
	<<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>
	5> crypto:crypto_update(StateEnc, <<"First bytes">>).
	<<67,44,216,166,25,130,203,5,66,6,162>>
	6> crypto:crypto_update(StateEnc, <<"Second bytes">>).
	<<16,79,94,115,234,197,94,253,16,144,151,41>>
	7>
	7> StateDec = crypto:crypto_init(aes_128_ctr, Key, IV, false). % decrypt -> false
	#Ref<0.3768901617.1128660994.124255>
	8> crypto:crypto_update(StateDec, <<67,44,216,166,25,130,203>>).
	<<"First b">>
	9> crypto:crypto_update(StateDec, <<5,66,6,162,16,79,94,115,234,197,
                                            94,253,16,144,151>>).
	<<"ytesSecond byte">>
	10> crypto:crypto_update(StateDec, <<41>>).
	<<"s">>
	11>

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.

For example, a simple server receiving text parts to encrypt and send the result back to the one who sent them (the Requester):


	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.

Example of crypto_one_time/5

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


	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> 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>>
	5>

The [<<"First bytes">>,<<"Second bytes">>] could of course have been one single binary: <<"First bytesSecond bytes">>.

Example of crypto_one_time_aead/6

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


	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>

The [<<"First bytes">>,<<"Second bytes">>] could of course have been one single binary: <<"First bytesSecond bytes">>.

Retired cipher names

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.

Instead of: Use: aes_cbc128 aes_128_cbc aes_cbc256 aes_256_cbc aes_cbc aes_128_cbc, aes_192_cbc, aes_256_cbcaes_ccm aes_128_ccm, aes_192_ccm, aes_256_ccmaes_cfb128 aes_128_cfb128, aes_192_cfb128, aes_256_cfb128aes_cfb8 aes_128_cfb8, aes_192_cfb8, aes_256_cfb8aes_ctr aes_128_ctr, aes_192_ctr, aes_256_ctraes_gcm aes_128_gcm, aes_192_gcm, aes_256_gcmdes3_cbc des_ede3_cbcdes3_cbf des_ede3_cfbdes3_cfb des_ede3_cfbdes_ede3 des_ede3_cbcdes_ede3_cbf des_ede3_cfb