PolarSSL is now part of ARM Official announcement and rebranded as mbed TLS.

API Documentation (Doxygen generated)

These pages are generated with doxygen directly from the source code!

chachapoly.h File Reference

This file contains the AEAD-ChaCha20-Poly1305 definitions and functions. More...

#include "config.h"
#include "poly1305.h"
#include "chacha20.h"
Include dependency graph for chachapoly.h:

Go to the source code of this file.

Data Structures

struct  mbedtls_chachapoly_context
 

Macros

#define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE   -0x0054
 The requested operation is not permitted in the current state. More...
 
#define MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED   -0x0056
 Authenticated decryption failed: data was not authentic. More...
 

Typedefs

typedef struct
mbedtls_chachapoly_context 
mbedtls_chachapoly_context
 

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

Detailed Description

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.

Author
Daniel King damak.nosp@m.i.gh.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Definition in file chachapoly.h.

Macro Definition Documentation

#define MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED   -0x0056

Authenticated decryption failed: data was not authentic.

Definition at line 46 of file chachapoly.h.

#define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE   -0x0054

The requested operation is not permitted in the current state.

Definition at line 45 of file chachapoly.h.

Typedef Documentation

Enumeration Type Documentation

Enumerator
MBEDTLS_CHACHAPOLY_ENCRYPT 

The mode value for performing encryption.

MBEDTLS_CHACHAPOLY_DECRYPT 

The mode value for performing decryption.

Definition at line 52 of file chachapoly.h.

Function Documentation

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.

Note
Before using this function, you must set the key with mbedtls_chachapoly_setkey().
Parameters
ctxThe ChaCha20-Poly1305 context to use (holds the key).
lengthThe length (in Bytes) of the data to decrypt.
nonceThe 96 Bit (12 bytes) nonce/IV to use.
aadThe buffer containing the additional authenticated data (AAD). This pointer can be NULL if aad_len == 0.
aad_lenThe length (in bytes) of the AAD data to process.
tagThe buffer holding the authentication tag. This must be a readable buffer of length 16 Bytes.
inputThe buffer containing the data to decrypt. This pointer can be NULL if ilen == 0.
outputThe buffer to where the decrypted data is written. This pointer can be NULL if ilen == 0.
Returns
0 on success.
MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED if the data was not authentic.
Another negative error code on other kinds of failure.
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.

Note
Before using this function, you must set the key with mbedtls_chachapoly_setkey().
Warning
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.
Parameters
ctxThe ChaCha20-Poly1305 context to use (holds the key). This must be initialized.
lengthThe length (in bytes) of the data to encrypt or decrypt.
nonceThe 96-bit (12 bytes) nonce/IV to use.
aadThe buffer containing the additional authenticated data (AAD). This pointer can be NULL if aad_len == 0.
aad_lenThe length (in bytes) of the AAD data to process.
inputThe buffer containing the data to encrypt or decrypt. This pointer can be NULL if ilen == 0.
outputThe buffer to where the encrypted or decrypted data is written. This pointer can be NULL if ilen == 0.
tagThe buffer to where the computed 128-bit (16 bytes) MAC is written. This must not be NULL.
Returns
0 on success.
A negative error code on failure.
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).

Parameters
ctxThe ChaCha20-Poly1305 context to use. This must be initialized.
macThe buffer to where the 128-bit (16 bytes) MAC is written.
Warning
Decryption with the piecewise API is discouraged, see the warning on mbedtls_chachapoly_init().
Returns
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.
void mbedtls_chachapoly_free ( mbedtls_chachapoly_context ctx)

This function releases and clears the specified ChaCha20-Poly1305 context.

Parameters
ctxThe 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().

Warning
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:

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.

Parameters
ctxThe ChachaPoly context to initialize. Must not be NULL.
int mbedtls_chachapoly_self_test ( int  verbose)

The ChaCha20-Poly1305 checkup routine.

Returns
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.

Parameters
ctxThe ChaCha20-Poly1305 context to which the key should be bound. This must be initialized.
keyThe 256 Bit (32 Bytes) key.
Returns
0 on success.
A negative error code on failure.
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.

Warning
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.
Note
If the context is being used for AAD only (no data to encrypt or decrypt) then mode can be set to any value.
Warning
Decryption with the piecewise API is discouraged, see the warning on mbedtls_chachapoly_init().
Parameters
ctxThe ChaCha20-Poly1305 context. This must be initialized and bound to a key.
nonceThe nonce/IV to use for the message. This must be a redable buffer of length 12 Bytes.
modeThe operation to perform: MBEDTLS_CHACHAPOLY_ENCRYPT or MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).
Returns
0 on success.
A negative error code on failure.
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.

Warning
Decryption with the piecewise API is discouraged, see the warning on mbedtls_chachapoly_init().
Parameters
ctxThe ChaCha20-Poly1305 context to use. This must be initialized.
lenThe length (in bytes) of the data to encrypt or decrypt.
inputThe buffer containing the data to encrypt or decrypt. This pointer can be NULL if len == 0.
outputThe 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.
Returns
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 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.

Note
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.

Warning
Decryption with the piecewise API is discouraged, see the warning on mbedtls_chachapoly_init().
Parameters
ctxThe ChaCha20-Poly1305 context. This must be initialized and bound to a key.
aad_lenThe length in Bytes of the AAD. The length has no restrictions.
aadBuffer containing the AAD. This pointer can be NULL if aad_len == 0.
Returns
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.