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