blob: a6a8cda74eb5093e4f554828ccc123f117c844fd [file] [log] [blame]
Daniel King34b822c2016-05-15 17:28:08 -03001/**
2 * \file chacha20.h
3 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +02004 * \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.
Daniel King34b822c2016-05-15 17:28:08 -030011 *
12 * \author Daniel King <damaki.gh@gmail.com>
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +020013 */
14
Bence Szépkúti86974652020-06-15 11:59:37 +020015/*
Bence Szépkúti1e148272020-08-07 13:07:28 +020016 * Copyright The Mbed TLS Contributors
Daniel King34b822c2016-05-15 17:28:08 -030017 * 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.
Daniel King34b822c2016-05-15 17:28:08 -030030 */
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +020031
Daniel King34b822c2016-05-15 17:28:08 -030032#ifndef MBEDTLS_CHACHA20_H
33#define MBEDTLS_CHACHA20_H
34
35#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010036#include "mbedtls/config.h"
Daniel King34b822c2016-05-15 17:28:08 -030037#else
38#include MBEDTLS_CONFIG_FILE
39#endif
40
Daniel King34b822c2016-05-15 17:28:08 -030041#include <stdint.h>
42#include <stddef.h>
43
Manuel Pégourié-Gonnard3798b6b2018-05-24 13:27:45 +020044#define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA -0x0051 /**< Invalid input parameter(s). */
Ron Eldor9924bdc2018-10-04 10:59:13 +030045
Manuel Pégourié-Gonnard823b7a02018-05-07 10:10:30 +020046#ifdef __cplusplus
47extern "C" {
48#endif
49
Manuel Pégourié-Gonnard95d0bdb2018-05-07 09:58:35 +020050#if !defined(MBEDTLS_CHACHA20_ALT)
51
Dawid Drozd428cc522018-07-24 10:02:47 +020052typedef struct mbedtls_chacha20_context
Daniel King34b822c2016-05-15 17:28:08 -030053{
Manuel Pégourié-Gonnard98fae6d2018-05-24 17:23:41 +020054 uint32_t state[16]; /*! The state (before round operations). */
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +020055 uint8_t keystream8[64]; /*! Leftover keystream bytes. */
56 size_t keystream_bytes_used; /*! Number of keystream bytes already used. */
Daniel King34b822c2016-05-15 17:28:08 -030057}
58mbedtls_chacha20_context;
59
Manuel Pégourié-Gonnard95d0bdb2018-05-07 09:58:35 +020060#else /* MBEDTLS_CHACHA20_ALT */
61#include "chacha20_alt.h"
62#endif /* MBEDTLS_CHACHA20_ALT */
63
Daniel King34b822c2016-05-15 17:28:08 -030064/**
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +020065 * \brief This function initializes the specified ChaCha20 context.
Daniel King34b822c2016-05-15 17:28:08 -030066 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +020067 * It must be the first API called before using
68 * the context.
69 *
70 * It is usually followed by calls to
71 * \c mbedtls_chacha20_setkey() and
72 * \c mbedtls_chacha20_starts(), then one or more calls to
73 * to \c mbedtls_chacha20_update(), and finally to
74 * \c mbedtls_chacha20_free().
75 *
76 * \param ctx The ChaCha20 context to initialize.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050077 * This must not be \c NULL.
Daniel King34b822c2016-05-15 17:28:08 -030078 */
79void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
80
81/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050082 * \brief This function releases and clears the specified
83 * ChaCha20 context.
Daniel King34b822c2016-05-15 17:28:08 -030084 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050085 * \param ctx The ChaCha20 context to clear. This may be \c NULL,
86 * in which case this function is a no-op. If it is not
87 * \c NULL, it must point to an initialized context.
88 *
Daniel King34b822c2016-05-15 17:28:08 -030089 */
90void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
91
92/**
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +020093 * \brief This function sets the encryption/decryption key.
Daniel King34b822c2016-05-15 17:28:08 -030094 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +020095 * \note After using this function, you must also call
96 * \c mbedtls_chacha20_starts() to set a nonce before you
97 * start encrypting/decrypting data with
98 * \c mbedtls_chacha_update().
Daniel King34b822c2016-05-15 17:28:08 -030099 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200100 * \param ctx The ChaCha20 context to which the key should be bound.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500101 * It must be initialized.
102 * \param key The encryption/decryption key. This must be \c 32 Bytes
103 * in length.
Daniel King34b822c2016-05-15 17:28:08 -0300104 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200105 * \return \c 0 on success.
106 * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
Daniel King34b822c2016-05-15 17:28:08 -0300107 */
108int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx,
109 const unsigned char key[32] );
110
111/**
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200112 * \brief This function sets the nonce and initial counter value.
Daniel King34b822c2016-05-15 17:28:08 -0300113 *
114 * \note A ChaCha20 context can be re-used with the same key by
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200115 * calling this function to change the nonce.
Daniel King34b822c2016-05-15 17:28:08 -0300116 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200117 * \warning You must never use the same nonce twice with the same key.
118 * This would void any confidentiality guarantees for the
119 * messages encrypted with the same nonce and key.
Daniel King34b822c2016-05-15 17:28:08 -0300120 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200121 * \param ctx The ChaCha20 context to which the nonce should be bound.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500122 * It must be initialized and bound to a key.
123 * \param nonce The nonce. This must be \c 12 Bytes in size.
124 * \param counter The initial counter value. This is usually \c 0.
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200125 *
126 * \return \c 0 on success.
127 * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
128 * NULL.
Daniel King34b822c2016-05-15 17:28:08 -0300129 */
130int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx,
131 const unsigned char nonce[12],
132 uint32_t counter );
133
134/**
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200135 * \brief This function encrypts or decrypts data.
Daniel King34b822c2016-05-15 17:28:08 -0300136 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200137 * Since ChaCha20 is a stream cipher, the same operation is
138 * used for encrypting and decrypting data.
Daniel King34b822c2016-05-15 17:28:08 -0300139 *
Manuel Pégourié-Gonnard502f1892018-05-07 11:57:05 +0200140 * \note The \p input and \p output pointers must either be equal or
141 * point to non-overlapping buffers.
Daniel King34b822c2016-05-15 17:28:08 -0300142 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200143 * \note \c mbedtls_chacha20_setkey() and
144 * \c mbedtls_chacha20_starts() must be called at least once
145 * to setup the context before this function can be called.
Daniel King34b822c2016-05-15 17:28:08 -0300146 *
Manuel Pégourié-Gonnardc7bc9e12018-06-18 10:30:30 +0200147 * \note This function can be called multiple times in a row in
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200148 * order to encrypt of decrypt data piecewise with the same
149 * key and nonce.
150 *
151 * \param ctx The ChaCha20 context to use for encryption or decryption.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500152 * It must be initialized and bound to a key and nonce.
153 * \param size The length of the input data in Bytes.
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200154 * \param input The buffer holding the input data.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500155 * This pointer can be \c NULL if `size == 0`.
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200156 * \param output The buffer holding the output data.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500157 * This must be able to hold \p size Bytes.
158 * This pointer can be \c NULL if `size == 0`.
Daniel King34b822c2016-05-15 17:28:08 -0300159 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200160 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500161 * \return A negative error code on failure.
Daniel King34b822c2016-05-15 17:28:08 -0300162 */
Daniel Kingbd920622016-05-15 19:56:20 -0300163int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200164 size_t size,
165 const unsigned char *input,
166 unsigned char *output );
Daniel King34b822c2016-05-15 17:28:08 -0300167
Daniel King34b822c2016-05-15 17:28:08 -0300168/**
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200169 * \brief This function encrypts or decrypts data with ChaCha20 and
170 * the given key and nonce.
Daniel King34b822c2016-05-15 17:28:08 -0300171 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200172 * Since ChaCha20 is a stream cipher, the same operation is
173 * used for encrypting and decrypting data.
Daniel King34b822c2016-05-15 17:28:08 -0300174 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200175 * \warning You must never use the same (key, nonce) pair more than
176 * once. This would void any confidentiality guarantees for
177 * the messages encrypted with the same nonce and key.
Daniel King34b822c2016-05-15 17:28:08 -0300178 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200179 * \note The \p input and \p output pointers must either be equal or
180 * point to non-overlapping buffers.
181 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500182 * \param key The encryption/decryption key.
183 * This must be \c 32 Bytes in length.
184 * \param nonce The nonce. This must be \c 12 Bytes in size.
185 * \param counter The initial counter value. This is usually \c 0.
186 * \param size The length of the input data in Bytes.
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200187 * \param input The buffer holding the input data.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500188 * This pointer can be \c NULL if `size == 0`.
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200189 * \param output The buffer holding the output data.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500190 * This must be able to hold \p size Bytes.
191 * This pointer can be \c NULL if `size == 0`.
Daniel King34b822c2016-05-15 17:28:08 -0300192 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200193 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500194 * \return A negative error code on failure.
Daniel King34b822c2016-05-15 17:28:08 -0300195 */
196int mbedtls_chacha20_crypt( const unsigned char key[32],
197 const unsigned char nonce[12],
198 uint32_t counter,
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200199 size_t size,
Daniel King34b822c2016-05-15 17:28:08 -0300200 const unsigned char* input,
201 unsigned char* output );
202
Manuel Pégourié-Gonnardc22e61a2018-05-24 13:51:05 +0200203#if defined(MBEDTLS_SELF_TEST)
Daniel King34b822c2016-05-15 17:28:08 -0300204/**
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200205 * \brief The ChaCha20 checkup routine.
Daniel King34b822c2016-05-15 17:28:08 -0300206 *
Manuel Pégourié-Gonnardb500f8b2018-05-08 12:43:48 +0200207 * \return \c 0 on success.
208 * \return \c 1 on failure.
Daniel King34b822c2016-05-15 17:28:08 -0300209 */
210int mbedtls_chacha20_self_test( int verbose );
Manuel Pégourié-Gonnardc22e61a2018-05-24 13:51:05 +0200211#endif /* MBEDTLS_SELF_TEST */
Daniel King34b822c2016-05-15 17:28:08 -0300212
Manuel Pégourié-Gonnard823b7a02018-05-07 10:10:30 +0200213#ifdef __cplusplus
214}
215#endif
216
Daniel King34b822c2016-05-15 17:28:08 -0300217#endif /* MBEDTLS_CHACHA20_H */