NAME

crypto_aead_lock, crypto_aead_unlock, crypto_lock, crypto_unlock — 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_aead_lock(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_aead_unlock(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. See crypto_key_exchange(3monocypher) for key exchange, and crypto_argon2i(3monocypher) for password key derivation.

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 intro(3monocypher) 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 intro(3monocypher) for details.

cipher_text: The encrypted message.

text_size: Length of both plain_text and cipher_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_aead_lock() and crypto_aead_unlock() 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 NULL if ad_size is zero. Setting ad_size to zero yields the same results as crypto_lock() and crypto_unlock().

ad_size: Length of the additional data, in bytes. That length is not authenticated. If the additional data is of variable length, the length should be appended to ad so it gets authenticated, and should be extracted from the end of the message when decrypting. Otherwise an attacker could provide a false length, effectively moving the boundary between the additional data and the ciphertext. This may cause buffer overflows in some programs.

An incremental interface is available; see crypto_lock_init(3monocypher).

RETURN VALUES

crypto_lock() and crypto_aead_lock() return nothing. They cannot fail. crypto_unlock() and crypto_aead_unlock() 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];  /* Reived 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 the XChacha20 (encryption) and Poly1305 (MAC) primitives. Chacha20 and Poly1305 are described in RFC 7539. 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).

IMPLEMENTATION DETAILS

crypto_aead_lock() and crypto_aead_unlock() do not authenticate the length themselves to make them compatible with crypto_lock() and crypto_unlock() when the size of the additional data is zero. This also simplifies the implementation.

This rarely causes problems in practice, because most of the time, the length of the additional data is either fixed or self-contained, and thus outside of attacker control.