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