crypto_lock_aead,
crypto_unlock_aead,
crypto_lock,
crypto_unlock —
authenticated encryption with additional
data
#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);
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_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
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.
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.
The following examples assume the existence of
arc4random_buf(), which fills the given buffer
with cryptographically secure random bytes. If
arc4random_buf() does not exist on your system,
see
intro(3monocypher) for
advice about how to generate cryptographically secure random bytes.
Encryption:
uint8_t key [32]; /* Random, secret session key */
uint8_t nonce [24]; /* Use only once per key */
uint8_t plain_text [12] = "Lorem ipsum"; /* Secret message */
uint8_t mac [16]; /* Message authentication code */
uint8_t cipher_text[12]; /* Encrypted message */
arc4random_buf(key, 32);
arc4random_buf(nonce, 24);
crypto_lock(mac, cipher_text, key, nonce, plain_text,
sizeof(plain_text));
/* Wipe secrets if they are no longer needed */
crypto_wipe(plain_text, 12);
crypto_wipe(key, 32);
/* Transmit cipher_text, nonce, and mac over the network,
* store them in a file, etc.
*/
To decrypt the above:
uint8_t key [32]; /* Same as the above */
uint8_t nonce [24]; /* Same as the above */
const uint8_t cipher_text[12]; /* Encrypted message */
const uint8_t mac [16]; /* Received along with text */
uint8_t plain_text [12]; /* Secret message */
if (crypto_unlock(plain_text, key, nonce, mac, cipher_text, 12)) {
/* The message is corrupted.
* Wipe key if it is no longer needed,
* and abort the decryption.
*/
crypto_wipe(key, 32);
} else {
/* ...do something with the decrypted text here... */
/* Finally, wipe secrets if they are no longer needed */
crypto_wipe(plain_text, 12);
crypto_wipe(key, 32);
}
In-place encryption:
uint8_t key [32]; /* Random, secret session key */
uint8_t nonce[24]; /* Use only once per key */
uint8_t text [12] = "Lorem ipsum"; /* Secret message */
uint8_t mac [16]; /* Message authentication code */
arc4random_buf(key, 32);
arc4random_buf(nonce, 24);
crypto_lock(mac, text, key, nonce, text, 12);
/* Wipe secrets if they are no longer needed */
crypto_wipe(key, 32);
/* Transmit cipher_text, nonce, and mac over the network,
* store them in a file, etc.
*/
In-place decryption:
uint8_t key [32]; /* Same as the above */
const uint8_t nonce[24]; /* Same as the above */
const uint8_t mac [16]; /* Received from along with text */
uint8_t text [12]; /* Message to decrypt */
if (crypto_unlock(text, key, nonce, mac, text, 12)) {
/* The message is corrupted.
* Wipe key if it is no longer needed,
* and abort the decryption.
*/
crypto_wipe(key, 32);
} else {
/* ...do something with the decrypted text here... */
/* Finally, wipe secrets if they are no longer needed */
crypto_wipe(text, 12);
crypto_wipe(key, 32);
}
crypto_key_exchange(3monocypher),
crypto_wipe(3monocypher),
intro(3monocypher)
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).
The
crypto_lock() and
crypto_unlock() functions first appeared in
Monocypher 0.1.
crypto_lock_aead() and
crypto_unlock_aead() were introduced in
Monocypher 1.1.0. In Monocypher 2.0.0, the underlying algorithms for these
functions were changed from a custom XChacha20/Poly1305 construction to an
implementation of RFC 7539 (now RFC 8439) with XChacha20 instead of Chacha20.
The
crypto_lock_encrypt() and
crypto_lock_auth() functions were removed in
Monocypher 2.0.0.