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