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