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