chacha20.h

00001 /**
00002  * \file chacha20.h
00003  *
00004  * \brief   This file contains ChaCha20 definitions and functions.
00005  *
00006  *          ChaCha20 is a stream cipher that can encrypt and decrypt
00007  *          information. ChaCha was created by Daniel Bernstein as a variant of
00008  *          its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf
00009  *          ChaCha20 is the variant with 20 rounds, that was also standardized
00010  *          in RFC 7539.
00011  *
00012  * \author Daniel King <damaki.gh@gmail.com>
00013  */
00014 
00015 /*  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
00016  *  SPDX-License-Identifier: Apache-2.0
00017  *
00018  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00019  *  not use this file except in compliance with the License.
00020  *  You may obtain a copy of the License at
00021  *
00022  *  http://www.apache.org/licenses/LICENSE-2.0
00023  *
00024  *  Unless required by applicable law or agreed to in writing, software
00025  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00026  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00027  *  See the License for the specific language governing permissions and
00028  *  limitations under the License.
00029  *
00030  *  This file is part of Mbed TLS (https://tls.mbed.org)
00031  */
00032 
00033 #ifndef MBEDTLS_CHACHA20_H
00034 #define MBEDTLS_CHACHA20_H
00035 
00036 #if !defined(MBEDTLS_CONFIG_FILE)
00037 #include "mbedtls/config.h"
00038 #else
00039 #include MBEDTLS_CONFIG_FILE
00040 #endif
00041 
00042 #include <stdint.h>
00043 #include <stddef.h>
00044 
00045 #define MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA         -0x0051 /**< Invalid input parameter(s). */
00046 
00047 /* MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE is deprecated and should not be
00048  * used. */
00049 #define MBEDTLS_ERR_CHACHA20_FEATURE_UNAVAILABLE    -0x0053 /**< Feature not available. For example, s part of the API is not implemented. */
00050 
00051 /* MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED is deprecated and should not be used.
00052  */
00053 #define MBEDTLS_ERR_CHACHA20_HW_ACCEL_FAILED        -0x0055  /**< Chacha20 hardware accelerator failed. */
00054 
00055 #ifdef __cplusplus
00056 extern "C" {
00057 #endif
00058 
00059 #if !defined(MBEDTLS_CHACHA20_ALT)
00060 
00061 typedef struct mbedtls_chacha20_context
00062 {
00063     uint32_t state[16];          /*! The state (before round operations). */
00064     uint8_t  keystream8[64];     /*! Leftover keystream bytes. */
00065     size_t keystream_bytes_used; /*! Number of keystream bytes already used. */
00066 }
00067 mbedtls_chacha20_context;
00068 
00069 #else  /* MBEDTLS_CHACHA20_ALT */
00070 #include "chacha20_alt.h"
00071 #endif /* MBEDTLS_CHACHA20_ALT */
00072 
00073 /**
00074  * \brief           This function initializes the specified ChaCha20 context.
00075  *
00076  *                  It must be the first API called before using
00077  *                  the context.
00078  *
00079  *                  It is usually followed by calls to
00080  *                  \c mbedtls_chacha20_setkey() and
00081  *                  \c mbedtls_chacha20_starts(), then one or more calls to
00082  *                  to \c mbedtls_chacha20_update(), and finally to
00083  *                  \c mbedtls_chacha20_free().
00084  *
00085  * \param ctx       The ChaCha20 context to initialize.
00086  *                  This must not be \c NULL.
00087  */
00088 void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
00089 
00090 /**
00091  * \brief           This function releases and clears the specified
00092  *                  ChaCha20 context.
00093  *
00094  * \param ctx       The ChaCha20 context to clear. This may be \c NULL,
00095  *                  in which case this function is a no-op. If it is not
00096  *                  \c NULL, it must point to an initialized context.
00097  *
00098  */
00099 void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
00100 
00101 /**
00102  * \brief           This function sets the encryption/decryption key.
00103  *
00104  * \note            After using this function, you must also call
00105  *                  \c mbedtls_chacha20_starts() to set a nonce before you
00106  *                  start encrypting/decrypting data with
00107  *                  \c mbedtls_chacha_update().
00108  *
00109  * \param ctx       The ChaCha20 context to which the key should be bound.
00110  *                  It must be initialized.
00111  * \param key       The encryption/decryption key. This must be \c 32 Bytes
00112  *                  in length.
00113  *
00114  * \return          \c 0 on success.
00115  * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
00116  */
00117 int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx,
00118                              const unsigned char key[32] );
00119 
00120 /**
00121  * \brief           This function sets the nonce and initial counter value.
00122  *
00123  * \note            A ChaCha20 context can be re-used with the same key by
00124  *                  calling this function to change the nonce.
00125  *
00126  * \warning         You must never use the same nonce twice with the same key.
00127  *                  This would void any confidentiality guarantees for the
00128  *                  messages encrypted with the same nonce and key.
00129  *
00130  * \param ctx       The ChaCha20 context to which the nonce should be bound.
00131  *                  It must be initialized and bound to a key.
00132  * \param nonce     The nonce. This must be \c 12 Bytes in size.
00133  * \param counter   The initial counter value. This is usually \c 0.
00134  *
00135  * \return          \c 0 on success.
00136  * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
00137  *                  NULL.
00138  */
00139 int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx,
00140                              const unsigned char nonce[12],
00141                              uint32_t counter );
00142 
00143 /**
00144  * \brief           This function encrypts or decrypts data.
00145  *
00146  *                  Since ChaCha20 is a stream cipher, the same operation is
00147  *                  used for encrypting and decrypting data.
00148  *
00149  * \note            The \p input and \p output pointers must either be equal or
00150  *                  point to non-overlapping buffers.
00151  *
00152  * \note            \c mbedtls_chacha20_setkey() and
00153  *                  \c mbedtls_chacha20_starts() must be called at least once
00154  *                  to setup the context before this function can be called.
00155  *
00156  * \note            This function can be called multiple times in a row in
00157  *                  order to encrypt of decrypt data piecewise with the same
00158  *                  key and nonce.
00159  *
00160  * \param ctx       The ChaCha20 context to use for encryption or decryption.
00161  *                  It must be initialized and bound to a key and nonce.
00162  * \param size      The length of the input data in Bytes.
00163  * \param input     The buffer holding the input data.
00164  *                  This pointer can be \c NULL if `size == 0`.
00165  * \param output    The buffer holding the output data.
00166  *                  This must be able to hold \p size Bytes.
00167  *                  This pointer can be \c NULL if `size == 0`.
00168  *
00169  * \return          \c 0 on success.
00170  * \return          A negative error code on failure.
00171  */
00172 int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
00173                              size_t size,
00174                              const unsigned char *input,
00175                              unsigned char *output );
00176 
00177 /**
00178  * \brief           This function encrypts or decrypts data with ChaCha20 and
00179  *                  the given key and nonce.
00180  *
00181  *                  Since ChaCha20 is a stream cipher, the same operation is
00182  *                  used for encrypting and decrypting data.
00183  *
00184  * \warning         You must never use the same (key, nonce) pair more than
00185  *                  once. This would void any confidentiality guarantees for
00186  *                  the messages encrypted with the same nonce and key.
00187  *
00188  * \note            The \p input and \p output pointers must either be equal or
00189  *                  point to non-overlapping buffers.
00190  *
00191  * \param key       The encryption/decryption key.
00192  *                  This must be \c 32 Bytes in length.
00193  * \param nonce     The nonce. This must be \c 12 Bytes in size.
00194  * \param counter   The initial counter value. This is usually \c 0.
00195  * \param size      The length of the input data in Bytes.
00196  * \param input     The buffer holding the input data.
00197  *                  This pointer can be \c NULL if `size == 0`.
00198  * \param output    The buffer holding the output data.
00199  *                  This must be able to hold \p size Bytes.
00200  *                  This pointer can be \c NULL if `size == 0`.
00201  *
00202  * \return          \c 0 on success.
00203  * \return          A negative error code on failure.
00204  */
00205 int mbedtls_chacha20_crypt( const unsigned char key[32],
00206                             const unsigned char nonce[12],
00207                             uint32_t counter,
00208                             size_t size,
00209                             const unsigned char* input,
00210                             unsigned char* output );
00211 
00212 #if defined(MBEDTLS_SELF_TEST)
00213 /**
00214  * \brief           The ChaCha20 checkup routine.
00215  *
00216  * \return          \c 0 on success.
00217  * \return          \c 1 on failure.
00218  */
00219 int mbedtls_chacha20_self_test( int verbose );
00220 #endif /* MBEDTLS_SELF_TEST */
00221 
00222 #ifdef __cplusplus
00223 }
00224 #endif
00225 
00226 #endif /* MBEDTLS_CHACHA20_H */