include/mbedtls/chacha20.h

0001 /**
0002  * \file chacha20.h
0003  *
0004  * \brief   This file contains ChaCha20 definitions and functions.
0005  *
0006  *          ChaCha20 is a stream cipher that can encrypt and decrypt
0007  *          information. ChaCha was created by Daniel Bernstein as a variant of
0008  *          its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf
0009  *          ChaCha20 is the variant with 20 rounds, that was also standardized
0010  *          in RFC 7539.
0011  *
0012  * \author Daniel King <damaki.gh@gmail.com>
0013  */
0014
0015 /*
0016  *  Copyright The Mbed TLS Contributors
0017  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0018  */
0019
0020 #ifndef MBEDTLS_CHACHA20_H
0021 #define MBEDTLS_CHACHA20_H
0022 #include "mbedtls/private_access.h"
0023
0024 #include "mbedtls/build_info.h"
0025
0026 #include <stdint.h>
0027 #include <stddef.h>
0028
0029 /** Invalid input parameter(s). */
0030 #define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA         -0x0051
0031
0032 #ifdef __cplusplus
0033 extern "C" {
0034 #endif
0035
0036 #if !defined(MBEDTLS_CHACHA20_ALT)
0037
0038 typedef struct mbedtls_chacha20_context {
0039     uint32_t MBEDTLS_PRIVATE(state)[16];          /*! The state (before round operations). */
0040     uint8_t  MBEDTLS_PRIVATE(keystream8)[64];     /*! Leftover keystream bytes. */
0041     size_t MBEDTLS_PRIVATE(keystream_bytes_used); /*! Number of keystream bytes already used. */
0042 }
0043 mbedtls_chacha20_context;
0044
0045 #else  /* MBEDTLS_CHACHA20_ALT */
0046 #include "chacha20_alt.h"
0047 #endif /* MBEDTLS_CHACHA20_ALT */
0048
0049 /**
0050  * \brief           This function initializes the specified ChaCha20 context.
0051  *
0052  *                  It must be the first API called before using
0053  *                  the context.
0054  *
0055  *                  It is usually followed by calls to
0056  *                  \c mbedtls_chacha20_setkey() and
0057  *                  \c mbedtls_chacha20_starts(), then one or more calls to
0058  *                  to \c mbedtls_chacha20_update(), and finally to
0059  *                  \c mbedtls_chacha20_free().
0060  *
0061  * \param ctx       The ChaCha20 context to initialize.
0062  *                  This must not be \c NULL.
0063  */
0064 void mbedtls_chacha20_init(mbedtls_chacha20_context *ctx);
0065
0066 /**
0067  * \brief           This function releases and clears the specified
0068  *                  ChaCha20 context.
0069  *
0070  * \param ctx       The ChaCha20 context to clear. This may be \c NULL,
0071  *                  in which case this function is a no-op. If it is not
0072  *                  \c NULL, it must point to an initialized context.
0073  *
0074  */
0075 void mbedtls_chacha20_free(mbedtls_chacha20_context *ctx);
0076
0077 /**
0078  * \brief           This function sets the encryption/decryption key.
0079  *
0080  * \note            After using this function, you must also call
0081  *                  \c mbedtls_chacha20_starts() to set a nonce before you
0082  *                  start encrypting/decrypting data with
0083  *                  \c mbedtls_chacha_update().
0084  *
0085  * \param ctx       The ChaCha20 context to which the key should be bound.
0086  *                  It must be initialized.
0087  * \param key       The encryption/decryption key. This must be \c 32 Bytes
0088  *                  in length.
0089  *
0090  * \return          \c 0 on success.
0091  * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
0092  */
0093 int mbedtls_chacha20_setkey(mbedtls_chacha20_context *ctx,
0094                             const unsigned char key[32]);
0095
0096 /**
0097  * \brief           This function sets the nonce and initial counter value.
0098  *
0099  * \note            A ChaCha20 context can be re-used with the same key by
0100  *                  calling this function to change the nonce.
0101  *
0102  * \warning         You must never use the same nonce twice with the same key.
0103  *                  This would void any confidentiality guarantees for the
0104  *                  messages encrypted with the same nonce and key.
0105  *
0106  * \param ctx       The ChaCha20 context to which the nonce should be bound.
0107  *                  It must be initialized and bound to a key.
0108  * \param nonce     The nonce. This must be \c 12 Bytes in size.
0109  * \param counter   The initial counter value. This is usually \c 0.
0110  *
0111  * \return          \c 0 on success.
0112  * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
0113  *                  NULL.
0114  */
0115 int mbedtls_chacha20_starts(mbedtls_chacha20_context *ctx,
0116                             const unsigned char nonce[12],
0117                             uint32_t counter);
0118
0119 /**
0120  * \brief           This function encrypts or decrypts data.
0121  *
0122  *                  Since ChaCha20 is a stream cipher, the same operation is
0123  *                  used for encrypting and decrypting data.
0124  *
0125  * \note            The \p input and \p output pointers must either be equal or
0126  *                  point to non-overlapping buffers.
0127  *
0128  * \note            \c mbedtls_chacha20_setkey() and
0129  *                  \c mbedtls_chacha20_starts() must be called at least once
0130  *                  to setup the context before this function can be called.
0131  *
0132  * \note            This function can be called multiple times in a row in
0133  *                  order to encrypt of decrypt data piecewise with the same
0134  *                  key and nonce.
0135  *
0136  * \param ctx       The ChaCha20 context to use for encryption or decryption.
0137  *                  It must be initialized and bound to a key and nonce.
0138  * \param size      The length of the input data in Bytes.
0139  * \param input     The buffer holding the input data.
0140  *                  This pointer can be \c NULL if `size == 0`.
0141  * \param output    The buffer holding the output data.
0142  *                  This must be able to hold \p size Bytes.
0143  *                  This pointer can be \c NULL if `size == 0`.
0144  *
0145  * \return          \c 0 on success.
0146  * \return          A negative error code on failure.
0147  */
0148 int mbedtls_chacha20_update(mbedtls_chacha20_context *ctx,
0149                             size_t size,
0150                             const unsigned char *input,
0151                             unsigned char *output);
0152
0153 /**
0154  * \brief           This function encrypts or decrypts data with ChaCha20 and
0155  *                  the given key and nonce.
0156  *
0157  *                  Since ChaCha20 is a stream cipher, the same operation is
0158  *                  used for encrypting and decrypting data.
0159  *
0160  * \warning         You must never use the same (key, nonce) pair more than
0161  *                  once. This would void any confidentiality guarantees for
0162  *                  the messages encrypted with the same nonce and key.
0163  *
0164  * \note            The \p input and \p output pointers must either be equal or
0165  *                  point to non-overlapping buffers.
0166  *
0167  * \param key       The encryption/decryption key.
0168  *                  This must be \c 32 Bytes in length.
0169  * \param nonce     The nonce. This must be \c 12 Bytes in size.
0170  * \param counter   The initial counter value. This is usually \c 0.
0171  * \param size      The length of the input data in Bytes.
0172  * \param input     The buffer holding the input data.
0173  *                  This pointer can be \c NULL if `size == 0`.
0174  * \param output    The buffer holding the output data.
0175  *                  This must be able to hold \p size Bytes.
0176  *                  This pointer can be \c NULL if `size == 0`.
0177  *
0178  * \return          \c 0 on success.
0179  * \return          A negative error code on failure.
0180  */
0181 int mbedtls_chacha20_crypt(const unsigned char key[32],
0182                            const unsigned char nonce[12],
0183                            uint32_t counter,
0184                            size_t size,
0185                            const unsigned char *input,
0186                            unsigned char *output);
0187
0188 #if defined(MBEDTLS_SELF_TEST)
0189 /**
0190  * \brief           The ChaCha20 checkup routine.
0191  *
0192  * \return          \c 0 on success.
0193  * \return          \c 1 on failure.
0194  */
0195 int mbedtls_chacha20_self_test(int verbose);
0196 #endif /* MBEDTLS_SELF_TEST */
0197
0198 #ifdef __cplusplus
0199 }
0200 #endif
0201
0202 #endif /* MBEDTLS_CHACHA20_H */