1 /** 2 * \file chacha20.h 3 * 4 * \brief This file contains ChaCha20 definitions and functions. 5 * 6 * ChaCha20 is a stream cipher that can encrypt and decrypt 7 * information. ChaCha was created by Daniel Bernstein as a variant of 8 * its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf 9 * ChaCha20 is the variant with 20 rounds, that was also standardized 10 * in RFC 7539. 11 * 12 * \author Daniel King <damaki.gh@gmail.com> 13 */ 14 15 /* 16 * Copyright The Mbed TLS Contributors 17 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 18 */ 19 20 #ifndef MBEDTLS_CHACHA20_H 21 #define MBEDTLS_CHACHA20_H 22 23 #if !defined(MBEDTLS_CONFIG_FILE) 24 #include "mbedtls/config.h" 25 #else 26 #include MBEDTLS_CONFIG_FILE 27 #endif 28 29 #include <stdint.h> 30 #include <stddef.h> 31 32 /** Invalid input parameter(s). */ 33 #define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA -0x0051 34 35 /* MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE is deprecated and should not be 36 * used. */ 37 /** Feature not available. For example, s part of the API is not implemented. */ 38 #define MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE -0x0053 39 40 /* MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED is deprecated and should not be used. 41 */ 42 /** Chacha20 hardware accelerator failed. */ 43 #define MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED -0x0055 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 #if !defined(MBEDTLS_CHACHA20_ALT) 50 51 typedef struct mbedtls_chacha20_context { 52 uint32_t state[16]; /*! The state (before round operations). */ 53 uint8_t keystream8[64]; /*! Leftover keystream bytes. */ 54 size_t keystream_bytes_used; /*! Number of keystream bytes already used. */ 55 } 56 mbedtls_chacha20_context; 57 58 #else /* MBEDTLS_CHACHA20_ALT */ 59 #include "chacha20_alt.h" 60 #endif /* MBEDTLS_CHACHA20_ALT */ 61 62 /** 63 * \brief This function initializes the specified ChaCha20 context. 64 * 65 * It must be the first API called before using 66 * the context. 67 * 68 * It is usually followed by calls to 69 * \c mbedtls_chacha20_setkey() and 70 * \c mbedtls_chacha20_starts(), then one or more calls to 71 * to \c mbedtls_chacha20_update(), and finally to 72 * \c mbedtls_chacha20_free(). 73 * 74 * \param ctx The ChaCha20 context to initialize. 75 * This must not be \c NULL. 76 */ 77 void mbedtls_chacha20_init(mbedtls_chacha20_context *ctx); 78 79 /** 80 * \brief This function releases and clears the specified 81 * ChaCha20 context. 82 * 83 * \param ctx The ChaCha20 context to clear. This may be \c NULL, 84 * in which case this function is a no-op. If it is not 85 * \c NULL, it must point to an initialized context. 86 * 87 */ 88 void mbedtls_chacha20_free(mbedtls_chacha20_context *ctx); 89 90 /** 91 * \brief This function sets the encryption/decryption key. 92 * 93 * \note After using this function, you must also call 94 * \c mbedtls_chacha20_starts() to set a nonce before you 95 * start encrypting/decrypting data with 96 * \c mbedtls_chacha_update(). 97 * 98 * \param ctx The ChaCha20 context to which the key should be bound. 99 * It must be initialized. 100 * \param key The encryption/decryption key. This must be \c 32 Bytes 101 * in length. 102 * 103 * \return \c 0 on success. 104 * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL. 105 */ 106 int mbedtls_chacha20_setkey(mbedtls_chacha20_context *ctx, 107 const unsigned char key[32]); 108 109 /** 110 * \brief This function sets the nonce and initial counter value. 111 * 112 * \note A ChaCha20 context can be re-used with the same key by 113 * calling this function to change the nonce. 114 * 115 * \warning You must never use the same nonce twice with the same key. 116 * This would void any confidentiality guarantees for the 117 * messages encrypted with the same nonce and key. 118 * 119 * \param ctx The ChaCha20 context to which the nonce should be bound. 120 * It must be initialized and bound to a key. 121 * \param nonce The nonce. This must be \c 12 Bytes in size. 122 * \param counter The initial counter value. This is usually \c 0. 123 * 124 * \return \c 0 on success. 125 * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is 126 * NULL. 127 */ 128 int mbedtls_chacha20_starts(mbedtls_chacha20_context *ctx, 129 const unsigned char nonce[12], 130 uint32_t counter); 131 132 /** 133 * \brief This function encrypts or decrypts data. 134 * 135 * Since ChaCha20 is a stream cipher, the same operation is 136 * used for encrypting and decrypting data. 137 * 138 * \note The \p input and \p output pointers must either be equal or 139 * point to non-overlapping buffers. 140 * 141 * \note \c mbedtls_chacha20_setkey() and 142 * \c mbedtls_chacha20_starts() must be called at least once 143 * to setup the context before this function can be called. 144 * 145 * \note This function can be called multiple times in a row in 146 * order to encrypt of decrypt data piecewise with the same 147 * key and nonce. 148 * 149 * \param ctx The ChaCha20 context to use for encryption or decryption. 150 * It must be initialized and bound to a key and nonce. 151 * \param size The length of the input data in Bytes. 152 * \param input The buffer holding the input data. 153 * This pointer can be \c NULL if `size == 0`. 154 * \param output The buffer holding the output data. 155 * This must be able to hold \p size Bytes. 156 * This pointer can be \c NULL if `size == 0`. 157 * 158 * \return \c 0 on success. 159 * \return A negative error code on failure. 160 */ 161 int mbedtls_chacha20_update(mbedtls_chacha20_context *ctx, 162 size_t size, 163 const unsigned char *input, 164 unsigned char *output); 165 166 /** 167 * \brief This function encrypts or decrypts data with ChaCha20 and 168 * the given key and nonce. 169 * 170 * Since ChaCha20 is a stream cipher, the same operation is 171 * used for encrypting and decrypting data. 172 * 173 * \warning You must never use the same (key, nonce) pair more than 174 * once. This would void any confidentiality guarantees for 175 * the messages encrypted with the same nonce and key. 176 * 177 * \note The \p input and \p output pointers must either be equal or 178 * point to non-overlapping buffers. 179 * 180 * \param key The encryption/decryption key. 181 * This must be \c 32 Bytes in length. 182 * \param nonce The nonce. This must be \c 12 Bytes in size. 183 * \param counter The initial counter value. This is usually \c 0. 184 * \param size The length of the input data in Bytes. 185 * \param input The buffer holding the input data. 186 * This pointer can be \c NULL if `size == 0`. 187 * \param output The buffer holding the output data. 188 * This must be able to hold \p size Bytes. 189 * This pointer can be \c NULL if `size == 0`. 190 * 191 * \return \c 0 on success. 192 * \return A negative error code on failure. 193 */ 194 int mbedtls_chacha20_crypt(const unsigned char key[32], 195 const unsigned char nonce[12], 196 uint32_t counter, 197 size_t size, 198 const unsigned char *input, 199 unsigned char *output); 200 201 #if defined(MBEDTLS_SELF_TEST) 202 /** 203 * \brief The ChaCha20 checkup routine. 204 * 205 * \return \c 0 on success. 206 * \return \c 1 on failure. 207 */ 208 int mbedtls_chacha20_self_test(int verbose); 209 #endif /* MBEDTLS_SELF_TEST */ 210 211 #ifdef __cplusplus 212 } 213 #endif 214 215 #endif /* MBEDTLS_CHACHA20_H */ 216