4 * \brief This file contains ChaCha20 definitions and functions.
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
12 * \author Daniel King <damaki.gh@gmail.com>
15 /* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
16 * SPDX-License-Identifier: Apache-2.0
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
22 * http://www.apache.org/licenses/LICENSE-2.0
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.
30 * This file is part of Mbed TLS (https://tls.mbed.org)
33 #ifndef MBEDTLS_CHACHA20_H
34 #define MBEDTLS_CHACHA20_H
36 #if !defined(MBEDTLS_CONFIG_FILE)
39 #include MBEDTLS_CONFIG_FILE
45 #define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA -0x0051 /**< Invalid input parameter(s). */
47 /* MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE is deprecated and should not be
49 #define MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE -0x0053 /**< Feature not available. For example, s part of the API is not implemented. */
51 /* MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED is deprecated and should not be used.
53 #define MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED -0x0055 /**< Chacha20 hardware accelerator failed. */
59 #if !defined(MBEDTLS_CHACHA20_ALT)
61 typedef struct mbedtls_chacha20_context
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. */
67 mbedtls_chacha20_context;
69 #else /* MBEDTLS_CHACHA20_ALT */
70 #include "chacha20_alt.h"
71 #endif /* MBEDTLS_CHACHA20_ALT */
74 * \brief This function initializes the specified ChaCha20 context.
76 * It must be the first API called before using
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().
85 * \param ctx The ChaCha20 context to initialize.
86 * This must not be \c NULL.
88 void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
91 * \brief This function releases and clears the specified
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.
99 void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
102 * \brief This function sets the encryption/decryption key.
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().
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
114 * \return \c 0 on success.
115 * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
117 int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx,
118 const unsigned char key[32] );
121 * \brief This function sets the nonce and initial counter value.
123 * \note A ChaCha20 context can be re-used with the same key by
124 * calling this function to change the nonce.
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.
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.
135 * \return \c 0 on success.
136 * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
139 int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx,
140 const unsigned char nonce[12],
144 * \brief This function encrypts or decrypts data.
146 * Since ChaCha20 is a stream cipher, the same operation is
147 * used for encrypting and decrypting data.
149 * \note The \p input and \p output pointers must either be equal or
150 * point to non-overlapping buffers.
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.
156 * \note This function can be called multiple times in a row in
157 * order to encrypt of decrypt data piecewise with the same
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`.
169 * \return \c 0 on success.
170 * \return A negative error code on failure.
172 int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
174 const unsigned char *input,
175 unsigned char *output );
178 * \brief This function encrypts or decrypts data with ChaCha20 and
179 * the given key and nonce.
181 * Since ChaCha20 is a stream cipher, the same operation is
182 * used for encrypting and decrypting data.
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.
188 * \note The \p input and \p output pointers must either be equal or
189 * point to non-overlapping buffers.
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`.
202 * \return \c 0 on success.
203 * \return A negative error code on failure.
205 int mbedtls_chacha20_crypt( const unsigned char key[32],
206 const unsigned char nonce[12],
209 const unsigned char* input,
210 unsigned char* output );
212 #if defined(MBEDTLS_SELF_TEST)
214 * \brief The ChaCha20 checkup routine.
216 * \return \c 0 on success.
217 * \return \c 1 on failure.
219 int mbedtls_chacha20_self_test( int verbose );
220 #endif /* MBEDTLS_SELF_TEST */
226 #endif /* MBEDTLS_CHACHA20_H */