mbed TLS v3.1.0
|
This file contains the AEAD-ChaCha20-Poly1305 definitions and functions. More...
#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/poly1305.h"
#include "chachapoly_alt.h"
Go to the source code of this file.
Macros | |
#define | MBEDTLS_ERR_CHACHAPOLY_BAD_STATE -0x0054 |
#define | MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED -0x0056 |
Enumerations | |
enum | mbedtls_chachapoly_mode_t { MBEDTLS_CHACHAPOLY_ENCRYPT, MBEDTLS_CHACHAPOLY_DECRYPT } |
Functions | |
void | mbedtls_chachapoly_init (mbedtls_chachapoly_context *ctx) |
This function initializes the specified ChaCha20-Poly1305 context. More... | |
void | mbedtls_chachapoly_free (mbedtls_chachapoly_context *ctx) |
This function releases and clears the specified ChaCha20-Poly1305 context. More... | |
int | mbedtls_chachapoly_setkey (mbedtls_chachapoly_context *ctx, const unsigned char key[32]) |
This function sets the ChaCha20-Poly1305 symmetric encryption key. More... | |
int | mbedtls_chachapoly_starts (mbedtls_chachapoly_context *ctx, const unsigned char nonce[12], mbedtls_chachapoly_mode_t mode) |
This function starts a ChaCha20-Poly1305 encryption or decryption operation. More... | |
int | mbedtls_chachapoly_update_aad (mbedtls_chachapoly_context *ctx, const unsigned char *aad, size_t aad_len) |
This function feeds additional data to be authenticated into an ongoing ChaCha20-Poly1305 operation. More... | |
int | mbedtls_chachapoly_update (mbedtls_chachapoly_context *ctx, size_t len, const unsigned char *input, unsigned char *output) |
Thus function feeds data to be encrypted or decrypted into an on-going ChaCha20-Poly1305 operation. More... | |
int | mbedtls_chachapoly_finish (mbedtls_chachapoly_context *ctx, unsigned char mac[16]) |
This function finished the ChaCha20-Poly1305 operation and generates the MAC (authentication tag). More... | |
int | mbedtls_chachapoly_encrypt_and_tag (mbedtls_chachapoly_context *ctx, size_t length, const unsigned char nonce[12], const unsigned char *aad, size_t aad_len, const unsigned char *input, unsigned char *output, unsigned char tag[16]) |
This function performs a complete ChaCha20-Poly1305 authenticated encryption with the previously-set key. More... | |
int | mbedtls_chachapoly_auth_decrypt (mbedtls_chachapoly_context *ctx, size_t length, const unsigned char nonce[12], const unsigned char *aad, size_t aad_len, const unsigned char tag[16], const unsigned char *input, unsigned char *output) |
This function performs a complete ChaCha20-Poly1305 authenticated decryption with the previously-set key. More... | |
int | mbedtls_chachapoly_self_test (int verbose) |
The ChaCha20-Poly1305 checkup routine. More... | |
This file contains the AEAD-ChaCha20-Poly1305 definitions and functions.
ChaCha20-Poly1305 is an algorithm for Authenticated Encryption with Associated Data (AEAD) that can be used to encrypt and authenticate data. It is based on ChaCha20 and Poly1305 by Daniel Bernstein and was standardized in RFC 7539.
Definition in file chachapoly.h.
#define MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED -0x0056 |
Authenticated decryption failed: data was not authentic.
Definition at line 44 of file chachapoly.h.
#define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE -0x0054 |
The requested operation is not permitted in the current state.
Definition at line 42 of file chachapoly.h.
Enumerator | |
---|---|
MBEDTLS_CHACHAPOLY_ENCRYPT |
The mode value for performing encryption. |
MBEDTLS_CHACHAPOLY_DECRYPT |
The mode value for performing decryption. |
Definition at line 50 of file chachapoly.h.
int mbedtls_chachapoly_auth_decrypt | ( | mbedtls_chachapoly_context * | ctx, |
size_t | length, | ||
const unsigned char | nonce[12], | ||
const unsigned char * | aad, | ||
size_t | aad_len, | ||
const unsigned char | tag[16], | ||
const unsigned char * | input, | ||
unsigned char * | output | ||
) |
This function performs a complete ChaCha20-Poly1305 authenticated decryption with the previously-set key.
mbedtls_chachapoly_setkey()
.ctx | The ChaCha20-Poly1305 context to use (holds the key). |
length | The length (in Bytes) of the data to decrypt. |
nonce | The 96 Bit (12 bytes) nonce/IV to use. |
aad | The buffer containing the additional authenticated data (AAD). This pointer can be NULL if aad_len == 0 . |
aad_len | The length (in bytes) of the AAD data to process. |
tag | The buffer holding the authentication tag. This must be a readable buffer of length 16 Bytes. |
input | The buffer containing the data to decrypt. This pointer can be NULL if ilen == 0 . |
output | The buffer to where the decrypted data is written. This pointer can be NULL if ilen == 0 . |
0
on success. int mbedtls_chachapoly_encrypt_and_tag | ( | mbedtls_chachapoly_context * | ctx, |
size_t | length, | ||
const unsigned char | nonce[12], | ||
const unsigned char * | aad, | ||
size_t | aad_len, | ||
const unsigned char * | input, | ||
unsigned char * | output, | ||
unsigned char | tag[16] | ||
) |
This function performs a complete ChaCha20-Poly1305 authenticated encryption with the previously-set key.
mbedtls_chachapoly_setkey()
.ctx | The ChaCha20-Poly1305 context to use (holds the key). This must be initialized. |
length | The length (in bytes) of the data to encrypt or decrypt. |
nonce | The 96-bit (12 bytes) nonce/IV to use. |
aad | The buffer containing the additional authenticated data (AAD). This pointer can be NULL if aad_len == 0 . |
aad_len | The length (in bytes) of the AAD data to process. |
input | The buffer containing the data to encrypt or decrypt. This pointer can be NULL if ilen == 0 . |
output | The buffer to where the encrypted or decrypted data is written. This pointer can be NULL if ilen == 0 . |
tag | The buffer to where the computed 128-bit (16 bytes) MAC is written. This must not be NULL . |
0
on success. int mbedtls_chachapoly_finish | ( | mbedtls_chachapoly_context * | ctx, |
unsigned char | mac[16] | ||
) |
This function finished the ChaCha20-Poly1305 operation and generates the MAC (authentication tag).
ctx | The ChaCha20-Poly1305 context to use. This must be initialized. |
mac | The buffer to where the 128-bit (16 bytes) MAC is written. |
mbedtls_chachapoly_init()
.0
on success. void mbedtls_chachapoly_free | ( | mbedtls_chachapoly_context * | ctx | ) |
This function releases and clears the specified ChaCha20-Poly1305 context.
ctx | The ChachaPoly context to clear. This may be NULL , in which case this function is a no-op. |
void mbedtls_chachapoly_init | ( | mbedtls_chachapoly_context * | ctx | ) |
This function initializes the specified ChaCha20-Poly1305 context.
It must be the first API called before using the context. It must be followed by a call to mbedtls_chachapoly_setkey()
before any operation can be done, and to mbedtls_chachapoly_free()
once all operations with that context have been finished.
In order to encrypt or decrypt full messages at once, for each message you should make a single call to mbedtls_chachapoly_crypt_and_tag()
or mbedtls_chachapoly_auth_decrypt()
.
In order to encrypt messages piecewise, for each message you should make a call to mbedtls_chachapoly_starts()
, then 0 or more calls to mbedtls_chachapoly_update_aad()
, then 0 or more calls to mbedtls_chachapoly_update()
, then one call to mbedtls_chachapoly_finish()
.
mbedtls_chachapoly_auth_decrypt()
when possible!If however this is not possible because the data is too large to fit in memory, you need to:
mbedtls_chachapoly_starts()
and (if needed) mbedtls_chachapoly_update_aad()
as above,mbedtls_chachapoly_update()
multiple times and ensure its output (the plaintext) is NOT used in any other way than placing it in temporary storage at this point,mbedtls_chachapoly_finish()
to compute the authentication tag and compared it in constant time to the tag received with the ciphertext.If the tags are not equal, you must immediately discard all previous outputs of mbedtls_chachapoly_update()
, otherwise you can now safely use the plaintext.
ctx | The ChachaPoly context to initialize. Must not be NULL . |
int mbedtls_chachapoly_self_test | ( | int | verbose | ) |
The ChaCha20-Poly1305 checkup routine.
0
on success. 1
on failure. int mbedtls_chachapoly_setkey | ( | mbedtls_chachapoly_context * | ctx, |
const unsigned char | key[32] | ||
) |
This function sets the ChaCha20-Poly1305 symmetric encryption key.
ctx | The ChaCha20-Poly1305 context to which the key should be bound. This must be initialized. |
key | The 256 Bit (32 Bytes) key. |
0
on success. int mbedtls_chachapoly_starts | ( | mbedtls_chachapoly_context * | ctx, |
const unsigned char | nonce[12], | ||
mbedtls_chachapoly_mode_t | mode | ||
) |
This function starts a ChaCha20-Poly1305 encryption or decryption operation.
mode
can be set to any value.mbedtls_chachapoly_init()
.ctx | The ChaCha20-Poly1305 context. This must be initialized and bound to a key. |
nonce | The nonce/IV to use for the message. This must be a redable buffer of length 12 Bytes. |
mode | The operation to perform: MBEDTLS_CHACHAPOLY_ENCRYPT or MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning). |
0
on success. int mbedtls_chachapoly_update | ( | mbedtls_chachapoly_context * | ctx, |
size_t | len, | ||
const unsigned char * | input, | ||
unsigned char * | output | ||
) |
Thus function feeds data to be encrypted or decrypted into an on-going ChaCha20-Poly1305 operation.
The direction (encryption or decryption) depends on the mode that was given when calling mbedtls_chachapoly_starts()
.
You may call this function multiple times to process an arbitrary amount of data. It is permitted to call this function 0 times, if no data is to be encrypted or decrypted.
mbedtls_chachapoly_init()
.ctx | The ChaCha20-Poly1305 context to use. This must be initialized. |
len | The length (in bytes) of the data to encrypt or decrypt. |
input | The buffer containing the data to encrypt or decrypt. This pointer can be NULL if len == 0 . |
output | The buffer to where the encrypted or decrypted data is written. This must be able to hold len bytes. This pointer can be NULL if len == 0 . |
0
on success. int mbedtls_chachapoly_update_aad | ( | mbedtls_chachapoly_context * | ctx, |
const unsigned char * | aad, | ||
size_t | aad_len | ||
) |
This function feeds additional data to be authenticated into an ongoing ChaCha20-Poly1305 operation.
The Additional Authenticated Data (AAD), also called Associated Data (AD) is only authenticated but not encrypted nor included in the encrypted output. It is usually transmitted separately from the ciphertext or computed locally by each party.
mbedtls_chachapoly_update()
.You may call this function multiple times to process an arbitrary amount of AAD. It is permitted to call this function 0 times, if no AAD is used.
This function cannot be called any more if data has been processed by mbedtls_chachapoly_update()
, or if the context has been finished.
mbedtls_chachapoly_init()
.ctx | The ChaCha20-Poly1305 context. This must be initialized and bound to a key. |
aad_len | The length in Bytes of the AAD. The length has no restrictions. |
aad | Buffer containing the AAD. This pointer can be NULL if aad_len == 0 . |
0
on success. ctx
or aad
are NULL.