Authenticated Encryption
Authenticated encryption with additional data.
Synopsis
#include <monocypher.h>
void crypto_lock(uint8_t mac[16],
uint8_t *cipher_text,
const uint8_t key[32],
const uint8_t nonce[24],
const uint8_t *plain_text,
size_t text_size);
int crypto_unlock(uint8_t *plain_text,
const uint8_t key[32],
const uint8_t nonce[24],
const uint8_t mac[16],
const uint8_t *cipher_text,
size_t text_size);
void crypto_lock_aead(uint8_t mac[16],
uint8_t *cipher_text,
const uint8_t key[32],
const uint8_t nonce[24],
const uint8_t *ad,
size_t ad_size,
const uint8_t *plain_text,
size_t text_size);
int crypto_unlock_aead(uint8_t *plain_text,
const uint8_t key[32],
const uint8_t nonce[24],
const uint8_t mac[16],
const uint8_t *ad,
size_t ad_size,
const uint8_t *cipher_text,
size_t text_size);
Description
crypto_lock() encrypts and authenticates a plaintext. It can be
decrypted by crypto_unlock(). The arguments are:
key: A 32-byte session key, shared between the sender and the recipient. It must be secret and random. Different methods can be used to produce and exchange this key, such as Diffie-Hellman key exchange, password key derivation (the password must be communicated on a secure channel), or even meeting physically.
nonce: A 24-byte number, used only once with any given session key. It does not need to be secret or random, but it does have to be unique. Never use the same nonce twice with the same key. This would reveal the XOR of 2 different messages, which allows decryption and forgeries. The easiest (and recommended) way to generate this nonce is to select it at random. See the introduction about random number generation (use your operating system's random number generator).
mac: A 16-byte message authentication code (MAC), that can only be produced by someone who knows the session key. This guarantee cannot be upheld if a nonce has been reused with the session key, because doing so allows the attacker to learn the authentication key associated with that nonce. The MAC is intended to be sent along with the ciphertext.
plain_text: The secret message. Its contents will be kept hidden from attackers. Its length however, will not. Be careful when combining encryption with compression. See the introduction for details.
cipher_text: The encrypted message.
text_size: Length of both
plain_textandcipher_text, in bytes.
The cipher_text and plain_text arguments may point to the same
buffer for in-place encryption. Otherwise, the buffers they point to
must not overlap.
crypto_unlock() first checks the integrity of an encrypted message.
If it has been corrupted, crypto_unlock() returns -1 immediately.
Otherwise, it decrypts the message, then returns zero. Always check
the return value.
crypto_lock_aead() and crypto_unlock_aead() are variants of
crypto_lock() and crypto_unlock(), permitting additional data.
Additional data is authenticated, but not encrypted. This is used to
authenticate relevant data that cannot be encrypted.
The arguments are:
ad: Additional data to authenticate. It will not be encrypted. May be
NULLifad_sizeis zero. Settingad_sizeto zero yields the same results ascrypto_lock()andcrypto_unlock().ad_size: Length of the additional data, in bytes.
An incremental interface is available.
Return values
crypto_lock() and crypto_lock_aead() return nothing.
crypto_unlock() and crypto_unlock_aead() return 0 on success or -1
if the message was corrupted (i.e. mac mismatched the combination of
key, nonce, ad and cipher_text). Corruption can be caused by
transmission errors, programmer error, or an attacker's interference.
plain_text does not need to be wiped if the decryption fails.
Examples
Encryption:
const uint8_t key [32]; /* Random, secret session key */
const uint8_t nonce [24]; /* Use only once per key */
const uint8_t plain_text [500]; /* Secret message */
uint8_t mac [16]; /* Message authentication code */
uint8_t cipher_text[500]; /* Encrypted message */
crypto_lock(mac, cipher_text, key, nonce, plain_text, 500);
/* Wipe secrets if they are no longer needed */
crypto_wipe(plain_text, 500);
crypto_wipe(key, 32);
/* Transmit cipher_text, nonce, and mac over the network */
To decrypt the above:
const uint8_t key [32]; /* Same as the above */
const uint8_t nonce [24]; /* Same as the above */
const uint8_t cipher_text[500]; /* Encrypted message */
const uint8_t mac [16]; /* Received from the network */
uint8_t plain_text [500]; /* Secret message */
if (crypto_unlock(plain_text, key, nonce, mac, cipher_text, 500)) {
/* The message is corrupted.
* Wipe key if it is no longer needed,
* and abort the decryption.
*/
crypto_wipe(key, 32);
}
/* Wipe secrets if they are no longer needed */
crypto_wipe(plain_text, 500);
crypto_wipe(key, 32);
In-place encryption:
const uint8_t key [32]; /* Random, secret session key */
const uint8_t nonce[24]; /* Use only once per key */
uint8_t text [500]; /* Secret message */
uint8_t mac [16]; /* Message authentication code */
crypto_lock(mac, text, key, nonce, text, 500);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key, 32);
/* Transmit text, nonce, and mac over the network */
In-place decryption:
const uint8_t key [32]; /* Same as the above */
const uint8_t nonce[24]; /* Same as the above */
const uint8_t mac [16]; /* Received from the network */
uint8_t text [500]; /* Message to decrypt */
if (crypto_unlock(text, key, nonce, mac, text, 500)) {
/* The message is corrupted.
* Wipe key if it is no longer needed,
* and abort the decryption.
*/
crypto_wipe(key, 32);
}
/* Wipe secrets if they are no longer needed */
crypto_wipe(text, 500);
crypto_wipe(key, 32);
Standards
These functions implement RFC 8439, with XChacha20 instead of Chacha20. XChacha20 derives from Chacha20 the same way XSalsa20 derives from Salsa20, and benefits from the same security reduction (proven secure as long as Chacha20 itself is secure).