mbed TLS v2.23.0: chacha20.h File Reference

mbed TLS v2.23.0

Data Structures | Macros | Typedefs | Functions
chacha20.h File Reference

This file contains ChaCha20 definitions and functions. More...

`#include "mbedtls/config.h"`
`#include <stdint.h>`
`#include <stddef.h>`
Include dependency graph for chacha20.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | mbedtls_chacha20_context

## Macros
#define | MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA -0x0051
#define | MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE -0x0053
#define | MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED -0x0055

## Typedefs
typedef struct mbedtls_chacha20_context | mbedtls_chacha20_context

## Functions
void | mbedtls_chacha20_init (mbedtls_chacha20_context *ctx)
| This function initializes the specified ChaCha20 context. More...
void | mbedtls_chacha20_free (mbedtls_chacha20_context *ctx)
| This function releases and clears the specified ChaCha20 context. More...
int | mbedtls_chacha20_setkey (mbedtls_chacha20_context *ctx, const unsigned char key[32])
| This function sets the encryption/decryption key. More...
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. More...
int | mbedtls_chacha20_update (mbedtls_chacha20_context *ctx, size_t size, const unsigned char *input, unsigned char *output)
| This function encrypts or decrypts data. More...
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. More...
int | mbedtls_chacha20_self_test (int verbose)
| The ChaCha20 checkup routine. More...

## Detailed Description

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 damak.nosp@m.i.gh.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Definition in file chacha20.h.

## Macro Definition Documentation

## ◆ MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA

#define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA -0x0051

Invalid input parameter(s).

Definition at line 47 of file chacha20.h.

## ◆ MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE

#define MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE -0x0053

Feature not available. For example, s part of the API is not implemented.

Definition at line 51 of file chacha20.h.

## ◆ MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED

#define MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED -0x0055

Chacha20 hardware accelerator failed.

Definition at line 55 of file chacha20.h.

## Typedef Documentation

## ◆ mbedtls_chacha20_context

typedef struct mbedtls_chacha20_context mbedtls_chacha20_context

## Function Documentation

## ◆ mbedtls_chacha20_crypt()

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.

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.

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

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.
  A negative error code on failure.

## ◆ mbedtls_chacha20_free()

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.

## ◆ mbedtls_chacha20_init()

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

## ◆ mbedtls_chacha20_self_test()

int mbedtls_chacha20_self_test | ( | int | verbose | ) |

The ChaCha20 checkup routine.

Returns
  `0` on success.
  `1` on failure.

## ◆ mbedtls_chacha20_setkey()

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.
  MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.

## ◆ mbedtls_chacha20_starts()

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.
  MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is NULL.

## ◆ mbedtls_chacha20_update()

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.
  `mbedtls_chacha20_setkey()` and `mbedtls_chacha20_starts()` must be called at least once to setup the context before this function can be called.
  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.
  A negative error code on failure.