4 * \brief This file contains ChaCha20 definitions and functions.
\r
6 * ChaCha20 is a stream cipher that can encrypt and decrypt
\r
7 * information. ChaCha was created by Daniel Bernstein as a variant of
\r
8 * its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf
\r
9 * ChaCha20 is the variant with 20 rounds, that was also standardized
\r
12 * \author Daniel King <damaki.gh@gmail.com>
\r
15 /* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
\r
16 * SPDX-License-Identifier: Apache-2.0
\r
18 * Licensed under the Apache License, Version 2.0 (the "License"); you may
\r
19 * not use this file except in compliance with the License.
\r
20 * You may obtain a copy of the License at
\r
22 * http://www.apache.org/licenses/LICENSE-2.0
\r
24 * Unless required by applicable law or agreed to in writing, software
\r
25 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
\r
26 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
27 * See the License for the specific language governing permissions and
\r
28 * limitations under the License.
\r
30 * This file is part of Mbed TLS (https://tls.mbed.org)
\r
33 #ifndef MBEDTLS_CHACHA20_H
\r
34 #define MBEDTLS_CHACHA20_H
\r
36 #if !defined(MBEDTLS_CONFIG_FILE)
\r
39 #include MBEDTLS_CONFIG_FILE
\r
45 #define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA -0x0051 /**< Invalid input parameter(s). */
\r
47 /* MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE is deprecated and should not be
\r
49 #define MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE -0x0053 /**< Feature not available. For example, s part of the API is not implemented. */
\r
51 /* MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED is deprecated and should not be used.
\r
53 #define MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED -0x0055 /**< Chacha20 hardware accelerator failed. */
\r
59 #if !defined(MBEDTLS_CHACHA20_ALT)
\r
61 typedef struct mbedtls_chacha20_context
\r
63 uint32_t state[16]; /*! The state (before round operations). */
\r
64 uint8_t keystream8[64]; /*! Leftover keystream bytes. */
\r
65 size_t keystream_bytes_used; /*! Number of keystream bytes already used. */
\r
67 mbedtls_chacha20_context;
\r
69 #else /* MBEDTLS_CHACHA20_ALT */
\r
70 #include "chacha20_alt.h"
\r
71 #endif /* MBEDTLS_CHACHA20_ALT */
\r
74 * \brief This function initializes the specified ChaCha20 context.
\r
76 * It must be the first API called before using
\r
79 * It is usually followed by calls to
\r
80 * \c mbedtls_chacha20_setkey() and
\r
81 * \c mbedtls_chacha20_starts(), then one or more calls to
\r
82 * to \c mbedtls_chacha20_update(), and finally to
\r
83 * \c mbedtls_chacha20_free().
\r
85 * \param ctx The ChaCha20 context to initialize.
\r
86 * This must not be \c NULL.
\r
88 void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
\r
91 * \brief This function releases and clears the specified
\r
94 * \param ctx The ChaCha20 context to clear. This may be \c NULL,
\r
95 * in which case this function is a no-op. If it is not
\r
96 * \c NULL, it must point to an initialized context.
\r
99 void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
\r
102 * \brief This function sets the encryption/decryption key.
\r
104 * \note After using this function, you must also call
\r
105 * \c mbedtls_chacha20_starts() to set a nonce before you
\r
106 * start encrypting/decrypting data with
\r
107 * \c mbedtls_chacha_update().
\r
109 * \param ctx The ChaCha20 context to which the key should be bound.
\r
110 * It must be initialized.
\r
111 * \param key The encryption/decryption key. This must be \c 32 Bytes
\r
114 * \return \c 0 on success.
\r
115 * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
\r
117 int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx,
\r
118 const unsigned char key[32] );
\r
121 * \brief This function sets the nonce and initial counter value.
\r
123 * \note A ChaCha20 context can be re-used with the same key by
\r
124 * calling this function to change the nonce.
\r
126 * \warning You must never use the same nonce twice with the same key.
\r
127 * This would void any confidentiality guarantees for the
\r
128 * messages encrypted with the same nonce and key.
\r
130 * \param ctx The ChaCha20 context to which the nonce should be bound.
\r
131 * It must be initialized and bound to a key.
\r
132 * \param nonce The nonce. This must be \c 12 Bytes in size.
\r
133 * \param counter The initial counter value. This is usually \c 0.
\r
135 * \return \c 0 on success.
\r
136 * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
\r
139 int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx,
\r
140 const unsigned char nonce[12],
\r
141 uint32_t counter );
\r
144 * \brief This function encrypts or decrypts data.
\r
146 * Since ChaCha20 is a stream cipher, the same operation is
\r
147 * used for encrypting and decrypting data.
\r
149 * \note The \p input and \p output pointers must either be equal or
\r
150 * point to non-overlapping buffers.
\r
152 * \note \c mbedtls_chacha20_setkey() and
\r
153 * \c mbedtls_chacha20_starts() must be called at least once
\r
154 * to setup the context before this function can be called.
\r
156 * \note This function can be called multiple times in a row in
\r
157 * order to encrypt of decrypt data piecewise with the same
\r
160 * \param ctx The ChaCha20 context to use for encryption or decryption.
\r
161 * It must be initialized and bound to a key and nonce.
\r
162 * \param size The length of the input data in Bytes.
\r
163 * \param input The buffer holding the input data.
\r
164 * This pointer can be \c NULL if `size == 0`.
\r
165 * \param output The buffer holding the output data.
\r
166 * This must be able to hold \p size Bytes.
\r
167 * This pointer can be \c NULL if `size == 0`.
\r
169 * \return \c 0 on success.
\r
170 * \return A negative error code on failure.
\r
172 int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
\r
174 const unsigned char *input,
\r
175 unsigned char *output );
\r
178 * \brief This function encrypts or decrypts data with ChaCha20 and
\r
179 * the given key and nonce.
\r
181 * Since ChaCha20 is a stream cipher, the same operation is
\r
182 * used for encrypting and decrypting data.
\r
184 * \warning You must never use the same (key, nonce) pair more than
\r
185 * once. This would void any confidentiality guarantees for
\r
186 * the messages encrypted with the same nonce and key.
\r
188 * \note The \p input and \p output pointers must either be equal or
\r
189 * point to non-overlapping buffers.
\r
191 * \param key The encryption/decryption key.
\r
192 * This must be \c 32 Bytes in length.
\r
193 * \param nonce The nonce. This must be \c 12 Bytes in size.
\r
194 * \param counter The initial counter value. This is usually \c 0.
\r
195 * \param size The length of the input data in Bytes.
\r
196 * \param input The buffer holding the input data.
\r
197 * This pointer can be \c NULL if `size == 0`.
\r
198 * \param output The buffer holding the output data.
\r
199 * This must be able to hold \p size Bytes.
\r
200 * This pointer can be \c NULL if `size == 0`.
\r
202 * \return \c 0 on success.
\r
203 * \return A negative error code on failure.
\r
205 int mbedtls_chacha20_crypt( const unsigned char key[32],
\r
206 const unsigned char nonce[12],
\r
209 const unsigned char* input,
\r
210 unsigned char* output );
\r
212 #if defined(MBEDTLS_SELF_TEST)
\r
214 * \brief The ChaCha20 checkup routine.
\r
216 * \return \c 0 on success.
\r
217 * \return \c 1 on failure.
\r
219 int mbedtls_chacha20_self_test( int verbose );
\r
220 #endif /* MBEDTLS_SELF_TEST */
\r
226 #endif /* MBEDTLS_CHACHA20_H */
\r