CRYPTO_LOCK(3MONOCYPHER) | 3MONOCYPHER | CRYPTO_LOCK(3MONOCYPHER) |
NAME
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);
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-based key derivation (the password must be communicated on a secure channel), or even meeting physically. See crypto_x25519() for a bulding block for a key exchange protocol and crypto_argon2i() for password-based 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 basically reveal the affected messages and leave you vulnerable to forgeries. The easiest (and recommended) way to generate this nonce is to select it at random. See intro() 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() 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 ascrypto_lock
() andcrypto_unlock
(). - ad_size
- Length of the additional data, in bytes.
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
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() 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); }
SEE ALSO
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).
HISTORY
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.
February 13, 2022 | Debian |