Did you know ... | Search Documentation: |
Symmetric encryption and decryption |
The following predicates provide symmetric encryption and decryption. This means that the same key is used in both cases.
PlainText must be a string, atom or list of codes or characters, and CipherText is created as a string. Key and IV are typically lists of bytes, though atoms and strings are also permitted. Algorithm must be an algorithm which your copy of OpenSSL knows about.
Keys and IVs can be chosen at random (using for example crypto_n_random_bytes/2) or derived from input keying material (IKM) using for example crypto_data_hkdf/4. This input is often a shared secret, such as a negotiated point on an elliptic curve, or the hash that was computed from a password via crypto_password_hash/3 with a freshly generated and specified salt.
Reusing the same combination of Key and IV
typically leaks at least
some information about the plaintext. For example, identical
plaintexts will then correspond to identical ciphertexts. For some
algorithms, reusing an IV with the same Key has
disastrous results and can cause the loss of all properties that are
otherwise guaranteed. Especially in such cases, an IV is also
called a
nonce (number used once). If an IV is not needed for
your algorithm (such as 'aes-128-ecb'
) then any value can
be provided as it will be ignored by the underlying implementation. Note
that such algorithms do not provide semantic security and are
thus insecure. You should use stronger algorithms instead.
It is safe to store and transfer the used initialization vector (or nonce) in plain text, but the key must be kept secret.
Commonly used algorithms include:
’chacha20-poly1305’
’aes-128-gcm’
’aes-128-cbc’
Options:
utf8
.
Alternatives are utf8
and octet
.block
. You can disable padding by supplying none
here. If padding is disabled for block ciphers, then the length of the
ciphertext must be a multiple of the block size.For example, with OpenSSL 1.1.0 and greater, we can use the ChaCha20 stream cipher with the Poly1305 authenticator. This cipher uses a 256-bit key and a 96-bit nonce, i.e., 32 and 12 bytes, respectively:
?- Algorithm = 'chacha20-poly1305', crypto_n_random_bytes(32, Key), crypto_n_random_bytes(12, IV), crypto_data_encrypt("this is some input", Algorithm, Key, IV, CipherText, [tag(Tag)]), crypto_data_decrypt(CipherText, Algorithm, Key, IV, RecoveredText, [tag(Tag)]). Algorithm = 'chacha20-poly1305', Key = [65, 147, 140, 197, 27, 60, 198, 50, 218|...], IV = [253, 232, 174, 84, 168, 208, 218, 168, 228|...], CipherText = <binary string>, Tag = [248, 220, 46, 62, 255, 9, 178, 130, 250|...], RecoveredText = "this is some input".
In this example, we use crypto_n_random_bytes/2 to generate a key and nonce from cryptographically secure random numbers. For repeated applications, you must ensure that a nonce is only used once together with the same key. Note that for authenticated encryption schemes, the tag that was computed during encryption is necessary for decryption. It is safe to store and transfer the tag in plain text.
utf8
.
Alternatives are utf8
and octet
.block
. You can disable padding by supplying none
here.