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