Monocypher

Boring crypto that simply works

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:

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:

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 7539, 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).