NAME
ccpl_init, ccpl_aad, ccpl_crypt, ccpl_encrypt, ccpl_decrypt, ccpl_final - encrypt/decrypt data using the ChaCha20-Poly1305 algorithm
SYNOPSIS
#include <limb/ccpl.h>
void ccpl_init(void *key, void *nonce, void *ctx) int ccpl_aad(const void *data, size_t dlen, void *ctx) void ccpl_crypt(void *dst, const void *data, size_t dlen, int encrypt, void *ctx) void ccpl_encrypt(void *dst, const void *data, size_t dlen, void *ctx) void ccpl_decrypt(void *dst, const void *data, size_t dlen, void *ctx) void ccpl_final(void *dst, void *ctx)
DESCRIPTION
The ccpl_init() function initializes the given ccpl context pointed by ctx
to encrypt/decrypt data using the ChaCha20-Poly1305 authenticated encryption
with additional data (AEAD) algorithm.
This implementation is conform to RFC 8439, as such the key pointed
to by key must be 256bit/32 bytes long, and the nonce pointed.by nonce must
be 96bit/12 bytes long.
In order to be secure, the given nonce must be different for each invocation
with the same key.
Limitations of message length are the same as described in chacha20_init(3), however an additional limitation, specific to this combined algorithm, also applies, and brings the maximum size of both the additional data and the encrypted data to 2^64 bytes each.
First, the ccpl_aad() function must be used to feed additional data pointed by
data of length dlen into the ccpl context pointed by ctx. Such data will
not be encrypted, but will be covered by the authentication code generated using
the Poly1305 algorithm.
You can call this function as many times as needed.
Then, the ccpl_crypt() function can be used to either encrypt or decrypt data
pointed by data of length dlen into the memory pointed by dst (which must
be able to store dlen bytes).
As with chacha20_crypt(3) it is possible to use the same memory area for both
data and dst, and have it processed in-place.
Though the data processing is the same for encrypting and decrypting using the
ChaCha20 cipher, a difference is made regarding the Poly1305 MAC, as it is
always the encrypted data that must be fed into it.
This is why the argument encrypt is needed, and must be a set to 1 when
encrypting data (thus feeding it to Poly1305 after processing through
the ChaCha20 cipher), and set to 0 when decrypting data (thus feeding it to
Poly1305 before processing through the ChaCha20 cipher).
All calls must be either of encrypting or decrypting, mixing both is invalid.
However, you can call the function (with the same value for encrypt) as many
times as needed.
As a convenience, the ccpl_encrypt() and ccpl_decrypt() macros are provided.
It is required that all additional data - fed through the ccpl_aad()
function - be fed into the ccpl ctx before any call is made to
ccpl_crypt().
The ccpl_final() function stores the computed Poly1305-based MAC from ctx
in binary form into dst, which must be able to store 16 bytes.
When decrypting data, the stored MAC should be compared to the one accompanying
the data. If bitwise identical, both the decrypted data and the additional data
fed into the ccpl ctx have been authenticated.
RETURN VALUE
The ccpl_aad() function returns 1 on success, and 0 on failure. The only
possible failure case is if a call to ccpl_crypt() has already been made for
the same context.