mbedtls/private/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 "tf-psa-crypto/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         PSA_ERROR_INVALID_ARGUMENT
0031
0032 #ifdef __cplusplus
0033 extern "C" {
0034 #endif
0035
0036 typedef struct mbedtls_chacha20_context {
0037     uint32_t MBEDTLS_PRIVATE(state)[16];          /*! The state (before round operations). */
0038     uint8_t  MBEDTLS_PRIVATE(keystream8)[64];     /*! Leftover keystream bytes. */
0039     size_t MBEDTLS_PRIVATE(keystream_bytes_used); /*! Number of keystream bytes already used. */
0040 }
0041 mbedtls_chacha20_context;
0042
0043 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
0044 /**
0045  * \brief           This function initializes the specified ChaCha20 context.
0046  *
0047  *                  It must be the first API called before using
0048  *                  the context.
0049  *
0050  *                  It is usually followed by calls to
0051  *                  \c mbedtls_chacha20_setkey() and
0052  *                  \c mbedtls_chacha20_starts(), then one or more calls to
0053  *                  to \c mbedtls_chacha20_update(), and finally to
0054  *                  \c mbedtls_chacha20_free().
0055  *
0056  * \param ctx       The ChaCha20 context to initialize.
0057  *                  This must not be \c NULL.
0058  */
0059 void mbedtls_chacha20_init(mbedtls_chacha20_context *ctx);
0060
0061 /**
0062  * \brief           This function releases and clears the specified
0063  *                  ChaCha20 context.
0064  *
0065  * \param ctx       The ChaCha20 context to clear. This may be \c NULL,
0066  *                  in which case this function is a no-op. If it is not
0067  *                  \c NULL, it must point to an initialized context.
0068  *
0069  */
0070 void mbedtls_chacha20_free(mbedtls_chacha20_context *ctx);
0071
0072 /**
0073  * \brief           This function sets the encryption/decryption key.
0074  *
0075  * \note            After using this function, you must also call
0076  *                  \c mbedtls_chacha20_starts() to set a nonce before you
0077  *                  start encrypting/decrypting data with
0078  *                  \c mbedtls_chacha_update().
0079  *
0080  * \param ctx       The ChaCha20 context to which the key should be bound.
0081  *                  It must be initialized.
0082  * \param key       The encryption/decryption key. This must be \c 32 Bytes
0083  *                  in length.
0084  *
0085  * \return          \c 0 on success.
0086  * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
0087  */
0088 int mbedtls_chacha20_setkey(mbedtls_chacha20_context *ctx,
0089                             const unsigned char key[32]);
0090
0091 /**
0092  * \brief           This function sets the nonce and initial counter value.
0093  *
0094  * \note            A ChaCha20 context can be re-used with the same key by
0095  *                  calling this function to change the nonce.
0096  *
0097  * \warning         You must never use the same nonce twice with the same key.
0098  *                  This would void any confidentiality guarantees for the
0099  *                  messages encrypted with the same nonce and key.
0100  *
0101  * \param ctx       The ChaCha20 context to which the nonce should be bound.
0102  *                  It must be initialized and bound to a key.
0103  * \param nonce     The nonce. This must be \c 12 Bytes in size.
0104  * \param counter   The initial counter value. This is usually \c 0.
0105  *
0106  * \return          \c 0 on success.
0107  * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
0108  *                  NULL.
0109  */
0110 int mbedtls_chacha20_starts(mbedtls_chacha20_context *ctx,
0111                             const unsigned char nonce[12],
0112                             uint32_t counter);
0113
0114 /**
0115  * \brief           This function encrypts or decrypts data.
0116  *
0117  *                  Since ChaCha20 is a stream cipher, the same operation is
0118  *                  used for encrypting and decrypting data.
0119  *
0120  * \note            The \p input and \p output pointers must either be equal or
0121  *                  point to non-overlapping buffers.
0122  *
0123  * \note            \c mbedtls_chacha20_setkey() and
0124  *                  \c mbedtls_chacha20_starts() must be called at least once
0125  *                  to setup the context before this function can be called.
0126  *
0127  * \note            This function can be called multiple times in a row in
0128  *                  order to encrypt of decrypt data piecewise with the same
0129  *                  key and nonce.
0130  *
0131  * \param ctx       The ChaCha20 context to use for encryption or decryption.
0132  *                  It must be initialized and bound to a key and nonce.
0133  * \param size      The length of the input data in Bytes.
0134  * \param input     The buffer holding the input data.
0135  *                  This pointer can be \c NULL if `size == 0`.
0136  * \param output    The buffer holding the output data.
0137  *                  This must be able to hold \p size Bytes.
0138  *                  This pointer can be \c NULL if `size == 0`.
0139  *
0140  * \return          \c 0 on success.
0141  * \return          A negative error code on failure.
0142  */
0143 int mbedtls_chacha20_update(mbedtls_chacha20_context *ctx,
0144                             size_t size,
0145                             const unsigned char *input,
0146                             unsigned char *output);
0147
0148 /**
0149  * \brief           This function encrypts or decrypts data with ChaCha20 and
0150  *                  the given key and nonce.
0151  *
0152  *                  Since ChaCha20 is a stream cipher, the same operation is
0153  *                  used for encrypting and decrypting data.
0154  *
0155  * \warning         You must never use the same (key, nonce) pair more than
0156  *                  once. This would void any confidentiality guarantees for
0157  *                  the messages encrypted with the same nonce and key.
0158  *
0159  * \note            The \p input and \p output pointers must either be equal or
0160  *                  point to non-overlapping buffers.
0161  *
0162  * \param key       The encryption/decryption key.
0163  *                  This must be \c 32 Bytes in length.
0164  * \param nonce     The nonce. This must be \c 12 Bytes in size.
0165  * \param counter   The initial counter value. This is usually \c 0.
0166  * \param size      The length of the input data in Bytes.
0167  * \param input     The buffer holding the input data.
0168  *                  This pointer can be \c NULL if `size == 0`.
0169  * \param output    The buffer holding the output data.
0170  *                  This must be able to hold \p size Bytes.
0171  *                  This pointer can be \c NULL if `size == 0`.
0172  *
0173  * \return          \c 0 on success.
0174  * \return          A negative error code on failure.
0175  */
0176 int mbedtls_chacha20_crypt(const unsigned char key[32],
0177                            const unsigned char nonce[12],
0178                            uint32_t counter,
0179                            size_t size,
0180                            const unsigned char *input,
0181                            unsigned char *output);
0182
0183 #if defined(MBEDTLS_SELF_TEST)
0184 /**
0185  * \brief           The ChaCha20 checkup routine.
0186  *
0187  * \return          \c 0 on success.
0188  * \return          \c 1 on failure.
0189  */
0190 int mbedtls_chacha20_self_test(int verbose);
0191 #endif /* MBEDTLS_SELF_TEST */
0192
0193 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */
0194
0195 #ifdef __cplusplus
0196 }
0197 #endif
0198
0199 #endif /* MBEDTLS_CHACHA20_H */