File chacha20.h

This file contains ChaCha20 definitions and functions.

     ChaCha20 is a stream cipher that can encrypt and decrypt
     information. ChaCha was created by Daniel Bernstein as a variant of
     its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf
     ChaCha20 is the variant with 20 rounds, that was also standardized
     in RFC 7539.

Author: Daniel King damaki.gh@gmail.com

Defines

MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA: Invalid input parameter(s).

Functions

void mbedtls_chacha20_init(mbedtls_chacha20_context *ctx)

This function initializes the specified ChaCha20 context.

             It must be the first API called before using
             the context.

             It is usually followed by calls to
             \c mbedtls_chacha20_setkey() and
             \c mbedtls_chacha20_starts(), then one or more calls to
             to \c mbedtls_chacha20_update(), and finally to
             \c mbedtls_chacha20_free().

Parameters: ctx – The ChaCha20 context to initialize. This must not be NULL.

void mbedtls_chacha20_free(mbedtls_chacha20_context *ctx)

This function releases and clears the specified ChaCha20 context.

Parameters: ctx – The ChaCha20 context to clear. This may be NULL, in which case this function is a no-op. If it is not NULL, it must point to an initialized context.

int mbedtls_chacha20_setkey(mbedtls_chacha20_context *ctx, const unsigned char key[32])

This function sets the encryption/decryption key.

Note

After using this function, you must also call mbedtls_chacha20_starts() to set a nonce before you start encrypting/decrypting data with mbedtls_chacha_update().

Parameters

ctx – The ChaCha20 context to which the key should be bound. It must be initialized.
key – The encryption/decryption key. This must be 32 Bytes in length.

Returns

0 on success.

Returns

MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.

int mbedtls_chacha20_starts(mbedtls_chacha20_context *ctx, const unsigned char nonce[12], uint32_t counter)

This function sets the nonce and initial counter value.

Note

A ChaCha20 context can be re-used with the same key by calling this function to change the nonce.

Warning

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

Parameters

ctx – The ChaCha20 context to which the nonce should be bound. It must be initialized and bound to a key.
nonce – The nonce. This must be 12 Bytes in size.
counter – The initial counter value. This is usually 0.

Returns

0 on success.

Returns

MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is NULL.

int mbedtls_chacha20_update(mbedtls_chacha20_context *ctx, size_t size, const unsigned char *input, unsigned char *output)

This function encrypts or decrypts data.

             Since ChaCha20 is a stream cipher, the same operation is
             used for encrypting and decrypting data.

Note

The input and output pointers must either be equal or point to non-overlapping buffers.

Note

mbedtls_chacha20_setkey() and mbedtls_chacha20_starts() must be called at least once to setup the context before this function can be called.

Note

This function can be called multiple times in a row in order to encrypt of decrypt data piecewise with the same key and nonce.

Parameters

ctx – The ChaCha20 context to use for encryption or decryption. It must be initialized and bound to a key and nonce.
size – The length of the input data in Bytes.
input – The buffer holding the input data. This pointer can be NULL if size == 0.
output – The buffer holding the output data. This must be able to hold size Bytes. This pointer can be NULL if size == 0.

Returns

0 on success.

Returns

A negative error code on failure.

int mbedtls_chacha20_crypt(const unsigned char key[32], const unsigned char nonce[12], uint32_t counter, size_t size, const unsigned char *input, unsigned char *output)

This function encrypts or decrypts data with ChaCha20 and the given key and nonce.

Since ChaCha20 is a stream cipher, the same operation is used for encrypting and decrypting data.

Note

The input and output pointers must either be equal or point to non-overlapping buffers.

Warning

You must never use the same (key, nonce) pair more than once. This would void any confidentiality guarantees for the messages encrypted with the same nonce and key.

Parameters

key – The encryption/decryption key. This must be 32 Bytes in length.
nonce – The nonce. This must be 12 Bytes in size.
counter – The initial counter value. This is usually 0.
size – The length of the input data in Bytes.
input – The buffer holding the input data. This pointer can be NULL if size == 0.
output – The buffer holding the output data. This must be able to hold size Bytes. This pointer can be NULL if size == 0.

Returns

0 on success.

Returns

A negative error code on failure.

int mbedtls_chacha20_self_test(int verbose)

The ChaCha20 checkup routine.

Returns: 0 on success.
Returns: 1 on failure.