chachapoly.h
mbedtls/private_access.h
mbedtls/build_info.h
mbedtls/poly1305.h
mbedtls/chacha20.h
crypto_builtin_composites.h
mbedtls/build_info.h
mbedtls/chacha20.h
chachapoly.h
mbedtls/check_config.h
mbedtls/config_adjust_legacy_crypto.h
mbedtls/config_adjust_psa_from_legacy.h
mbedtls/config_adjust_psa_superset_legacy.h
mbedtls/config_adjust_ssl.h
mbedtls/config_adjust_x509.h
mbedtls/config_psa.h
mbedtls/mbedtls_config.h
mbedtls/poly1305.h
mbedtls/private_access.h
psa/crypto_adjust_auto_enabled.h
psa/crypto_adjust_config_dependencies.h
psa/crypto_adjust_config_key_pair_types.h
psa/crypto_adjust_config_synonyms.h
psa/crypto_legacy.h
limits.h
stddef.h
stdint.h
chachapoly.h
debug.h
net_sockets.h
oid.h
pk.h
pkcs7.h
psa_util.h
ssl.h
ssl_cache.h
ssl_ciphersuites.h
ssl_cookie.h
ssl_ticket.h
x509.h
x509_crl.h
x509_crt.h
x509_csr.h
crypto.h
crypto_builtin_composites.h
crypto_driver_contexts_composites.h
crypto_struct.h
mbedtls_chachapoly_context
MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
-0x0054

The requested operation is not permitted in the current state.

MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
-0x0056

Authenticated decryption failed: data was not authentic.

mbedtls_chachapoly_mode_t
MBEDTLS_CHACHAPOLY_ENCRYPT

The mode value for performing encryption.

MBEDTLS_CHACHAPOLY_DECRYPT

The mode value for performing decryption.

struct mbedtls_chachapoly_context typedef struct mbedtls_chachapoly_context mbedtls_chachapoly_context mbedtls_chachapoly_context
void void mbedtls_chachapoly_init (mbedtls_chachapoly_context *ctx) 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 \c mbedtls_chachapoly_setkey() before any operation can be done, and to \c 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 \c mbedtls_chachapoly_crypt_and_tag() or \c mbedtls_chachapoly_auth_decrypt(). In order to encrypt messages piecewise, for each message you should make a call to \c mbedtls_chachapoly_starts(), then 0 or more calls to \c mbedtls_chachapoly_update_aad(), then 0 or more calls to \c mbedtls_chachapoly_update(), then one call to \c mbedtls_chachapoly_finish().

Decryption with the piecewise API is discouraged! Always use `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:

- call `mbedtls_chachapoly_starts()` and (if needed) `mbedtls_chachapoly_update_aad()` as above,

- call `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,

- call `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`.

void void mbedtls_chachapoly_free (mbedtls_chachapoly_context *ctx) 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.

int int mbedtls_chachapoly_setkey (mbedtls_chachapoly_context *ctx, const unsigned char key[32]) 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.

A negative error code on failure.

int int mbedtls_chachapoly_starts (mbedtls_chachapoly_context *ctx, const unsigned char nonce[12], mbedtls_chachapoly_mode_t mode) 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.

You must never use the same nonce twice with the same key. This would void any confidentiality and authenticity guarantees for the messages encrypted with the same nonce and key.

If the context is being used for AAD only (no data to encrypt or decrypt) then `mode` can be set to any value.

Decryption with the piecewise API is discouraged, see the warning on `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 readable buffer of length `12` Bytes.

mode

The operation to perform: MBEDTLS_CHACHAPOLY_ENCRYPT or MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).

`0` on success.

A negative error code on failure.

int int mbedtls_chachapoly_update_aad (mbedtls_chachapoly_context *ctx, const unsigned char *aad, size_t aad_len) 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.

This function is called before data is encrypted/decrypted. I.e. call this function to process the AAD before calling `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.

Decryption with the piecewise API is discouraged, see the warning on `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.

MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA if `ctx` or `aad` are NULL.

MBEDTLS_ERR_CHACHAPOLY_BAD_STATE if the operations has not been started or has been finished, or if the AAD has been finished.

int int mbedtls_chachapoly_update (mbedtls_chachapoly_context *ctx, size_t len, const unsigned char *input, unsigned char *output) 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.

Decryption with the piecewise API is discouraged, see the warning on `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.

MBEDTLS_ERR_CHACHAPOLY_BAD_STATE if the operation has not been started or has been finished.

Another negative error code on other kinds of failure.

int int mbedtls_chachapoly_finish (mbedtls_chachapoly_context *ctx, unsigned char mac[16]) 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.

Decryption with the piecewise API is discouraged, see the warning on `mbedtls_chachapoly_init()`.

`0` on success.

MBEDTLS_ERR_CHACHAPOLY_BAD_STATE if the operation has not been started or has been finished.

Another negative error code on other kinds of failure.

int 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]) 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.

Before using this function, you must set the key with `mbedtls_chachapoly_setkey()`.

You must never use the same nonce twice with the same key. This would void any confidentiality and authenticity guarantees for the messages encrypted with the same nonce and key.

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.

A negative error code on failure.

int 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) 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.

Before using this function, you must set the key with `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.

MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED if the data was not authentic.

Another negative error code on other kinds of failure.

int int mbedtls_chachapoly_self_test (int verbose) mbedtls_chachapoly_self_test int verbose

The ChaCha20-Poly1305 checkup routine.

`0` on success.

`1` on failure.

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.

Daniel King damaki.gh@gmail.com

    /*
    *CopyrightTheMbedTLSContributors
    *SPDX-License-Identifier:Apache-2.0ORGPL-2.0-or-later
    */

    #ifndefMBEDTLS_CHACHAPOLY_H
    #defineMBEDTLS_CHACHAPOLY_H
    #include"mbedtls/private_access.h"

    #include"mbedtls/build_info.h"

    /*forsharederrorcodes*/
    #include"mbedtls/poly1305.h"

    #defineMBEDTLS_ERR_CHACHAPOLY_BAD_STATE-0x0054
    #defineMBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED-0x0056

    #ifdef__cplusplus
    extern"C"{
    #endif

    typedefenum{
    MBEDTLS_CHACHAPOLY_ENCRYPT,
    MBEDTLS_CHACHAPOLY_DECRYPT
    }
    mbedtls_chachapoly_mode_t;

    #if!defined(MBEDTLS_CHACHAPOLY_ALT)

    #include"mbedtls/chacha20.h"

    typedefstructmbedtls_chachapoly_context{
    mbedtls_chacha20_contextMBEDTLS_PRIVATE(chacha20_ctx);
    mbedtls_poly1305_contextMBEDTLS_PRIVATE(poly1305_ctx);
    uint64_tMBEDTLS_PRIVATE(aad_len);
    uint64_tMBEDTLS_PRIVATE(ciphertext_len);
    intMBEDTLS_PRIVATE(state);
    mbedtls_chachapoly_mode_tMBEDTLS_PRIVATE(mode);
    }
    mbedtls_chachapoly_context;

    #else/*!MBEDTLS_CHACHAPOLY_ALT*/
    #include"chachapoly_alt.h"
    #endif/*!MBEDTLS_CHACHAPOLY_ALT*/

    voidmbedtls_chachapoly_init(mbedtls_chachapoly_context*ctx);

    voidmbedtls_chachapoly_free(mbedtls_chachapoly_context*ctx);

    intmbedtls_chachapoly_setkey(mbedtls_chachapoly_context*ctx,
    constunsignedcharkey[32]);

    intmbedtls_chachapoly_starts(mbedtls_chachapoly_context*ctx,
    constunsignedcharnonce[12],
    mbedtls_chachapoly_mode_tmode);

    intmbedtls_chachapoly_update_aad(mbedtls_chachapoly_context*ctx,
    constunsignedchar*aad,
    size_taad_len);

    intmbedtls_chachapoly_update(mbedtls_chachapoly_context*ctx,
    size_tlen,
    constunsignedchar*input,
    unsignedchar*output);

    intmbedtls_chachapoly_finish(mbedtls_chachapoly_context*ctx,
    unsignedcharmac[16]);

    intmbedtls_chachapoly_encrypt_and_tag(mbedtls_chachapoly_context*ctx,
    size_tlength,
    constunsignedcharnonce[12],
    constunsignedchar*aad,
    size_taad_len,
    constunsignedchar*input,
    unsignedchar*output,
    unsignedchartag[16]);

    intmbedtls_chachapoly_auth_decrypt(mbedtls_chachapoly_context*ctx,
    size_tlength,
    constunsignedcharnonce[12],
    constunsignedchar*aad,
    size_taad_len,
    constunsignedchartag[16],
    constunsignedchar*input,
    unsignedchar*output);

    #ifdefined(MBEDTLS_SELF_TEST)
    intmbedtls_chachapoly_self_test(intverbose);
    #endif/*MBEDTLS_SELF_TEST*/

    #ifdef__cplusplus
    }
    #endif

    #endif/*MBEDTLS_CHACHAPOLY_H*/