chachapoly.h

00001 /**
00002  * \file chachapoly.h
00003  *
00004  * \brief   This file contains the AEAD-ChaCha20-Poly1305 definitions and
00005  *          functions.
00006  *
00007  *          ChaCha20-Poly1305 is an algorithm for Authenticated Encryption
00008  *          with Associated Data (AEAD) that can be used to encrypt and
00009  *          authenticate data. It is based on ChaCha20 and Poly1305 by Daniel
00010  *          Bernstein and was standardized 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_CHACHAPOLY_H
00034 #define MBEDTLS_CHACHAPOLY_H
00035 
00036 #if !defined(MBEDTLS_CONFIG_FILE)
00037 #include "mbedtls/config.h"
00038 #else
00039 #include MBEDTLS_CONFIG_FILE
00040 #endif
00041 
00042 /* for shared error codes */
00043 #include "mbedtls/poly1305.h"
00044 
00045 #define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE            -0x0054 /**< The requested operation is not permitted in the current state. */
00046 #define MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED          -0x0056 /**< Authenticated decryption failed: data was not authentic. */
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 
00052 typedef enum
00053 {
00054     MBEDTLS_CHACHAPOLY_ENCRYPT,     /**< The mode value for performing encryption. */
00055     MBEDTLS_CHACHAPOLY_DECRYPT      /**< The mode value for performing decryption. */
00056 }
00057 mbedtls_chachapoly_mode_t ;
00058 
00059 #if !defined(MBEDTLS_CHACHAPOLY_ALT)
00060 
00061 #include "mbedtls/chacha20.h"
00062 
00063 typedef struct mbedtls_chachapoly_context
00064 {
00065     mbedtls_chacha20_context chacha20_ctx;  /**< The ChaCha20 context. */
00066     mbedtls_poly1305_context poly1305_ctx;  /**< The Poly1305 context. */
00067     uint64_t aad_len;                       /**< The length (bytes) of the Additional Authenticated Data. */
00068     uint64_t ciphertext_len;                /**< The length (bytes) of the ciphertext. */
00069     int state;                              /**< The current state of the context. */
00070     mbedtls_chachapoly_mode_t  mode;         /**< Cipher mode (encrypt or decrypt). */
00071 }
00072 mbedtls_chachapoly_context;
00073 
00074 #else /* !MBEDTLS_CHACHAPOLY_ALT */
00075 #include "chachapoly_alt.h"
00076 #endif /* !MBEDTLS_CHACHAPOLY_ALT */
00077 
00078 /**
00079  * \brief           This function initializes the specified ChaCha20-Poly1305 context.
00080  *
00081  *                  It must be the first API called before using
00082  *                  the context. It must be followed by a call to
00083  *                  \c mbedtls_chachapoly_setkey() before any operation can be
00084  *                  done, and to \c mbedtls_chachapoly_free() once all
00085  *                  operations with that context have been finished.
00086  *
00087  *                  In order to encrypt or decrypt full messages at once, for
00088  *                  each message you should make a single call to
00089  *                  \c mbedtls_chachapoly_crypt_and_tag() or
00090  *                  \c mbedtls_chachapoly_auth_decrypt().
00091  *
00092  *                  In order to encrypt messages piecewise, for each
00093  *                  message you should make a call to
00094  *                  \c mbedtls_chachapoly_starts(), then 0 or more calls to
00095  *                  \c mbedtls_chachapoly_update_aad(), then 0 or more calls to
00096  *                  \c mbedtls_chachapoly_update(), then one call to
00097  *                  \c mbedtls_chachapoly_finish().
00098  *
00099  * \warning         Decryption with the piecewise API is discouraged! Always
00100  *                  use \c mbedtls_chachapoly_auth_decrypt() when possible!
00101  *
00102  *                  If however this is not possible because the data is too
00103  *                  large to fit in memory, you need to:
00104  *
00105  *                  - call \c mbedtls_chachapoly_starts() and (if needed)
00106  *                  \c mbedtls_chachapoly_update_aad() as above,
00107  *                  - call \c mbedtls_chachapoly_update() multiple times and
00108  *                  ensure its output (the plaintext) is NOT used in any other
00109  *                  way than placing it in temporary storage at this point,
00110  *                  - call \c mbedtls_chachapoly_finish() to compute the
00111  *                  authentication tag and compared it in constant time to the
00112  *                  tag received with the ciphertext.
00113  *
00114  *                  If the tags are not equal, you must immediately discard
00115  *                  all previous outputs of \c mbedtls_chachapoly_update(),
00116  *                  otherwise you can now safely use the plaintext.
00117  *
00118  * \param ctx       The ChachaPoly context to initialize. Must not be \c NULL.
00119  */
00120 void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx );
00121 
00122 /**
00123  * \brief           This function releases and clears the specified
00124  *                  ChaCha20-Poly1305 context.
00125  *
00126  * \param ctx       The ChachaPoly context to clear. This may be \c NULL, in which
00127  *                  case this function is a no-op.
00128  */
00129 void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx );
00130 
00131 /**
00132  * \brief           This function sets the ChaCha20-Poly1305
00133  *                  symmetric encryption key.
00134  *
00135  * \param ctx       The ChaCha20-Poly1305 context to which the key should be
00136  *                  bound. This must be initialized.
00137  * \param key       The \c 256 Bit (\c 32 Bytes) key.
00138  *
00139  * \return          \c 0 on success.
00140  * \return          A negative error code on failure.
00141  */
00142 int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx,
00143                                const unsigned char key[32] );
00144 
00145 /**
00146  * \brief           This function starts a ChaCha20-Poly1305 encryption or
00147  *                  decryption operation.
00148  *
00149  * \warning         You must never use the same nonce twice with the same key.
00150  *                  This would void any confidentiality and authenticity
00151  *                  guarantees for the messages encrypted with the same nonce
00152  *                  and key.
00153  *
00154  * \note            If the context is being used for AAD only (no data to
00155  *                  encrypt or decrypt) then \p mode can be set to any value.
00156  *
00157  * \warning         Decryption with the piecewise API is discouraged, see the
00158  *                  warning on \c mbedtls_chachapoly_init().
00159  *
00160  * \param ctx       The ChaCha20-Poly1305 context. This must be initialized
00161  *                  and bound to a key.
00162  * \param nonce     The nonce/IV to use for the message.
00163  *                  This must be a redable buffer of length \c 12 Bytes.
00164  * \param mode      The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
00165  *                  #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).
00166  *
00167  * \return          \c 0 on success.
00168  * \return          A negative error code on failure.
00169  */
00170 int mbedtls_chachapoly_starts( mbedtls_chachapoly_context *ctx,
00171                                const unsigned char nonce[12],
00172                                mbedtls_chachapoly_mode_t  mode );
00173 
00174 /**
00175  * \brief           This function feeds additional data to be authenticated
00176  *                  into an ongoing ChaCha20-Poly1305 operation.
00177  *
00178  *                  The Additional Authenticated Data (AAD), also called
00179  *                  Associated Data (AD) is only authenticated but not
00180  *                  encrypted nor included in the encrypted output. It is
00181  *                  usually transmitted separately from the ciphertext or
00182  *                  computed locally by each party.
00183  *
00184  * \note            This function is called before data is encrypted/decrypted.
00185  *                  I.e. call this function to process the AAD before calling
00186  *                  \c mbedtls_chachapoly_update().
00187  *
00188  *                  You may call this function multiple times to process
00189  *                  an arbitrary amount of AAD. It is permitted to call
00190  *                  this function 0 times, if no AAD is used.
00191  *
00192  *                  This function cannot be called any more if data has
00193  *                  been processed by \c mbedtls_chachapoly_update(),
00194  *                  or if the context has been finished.
00195  *
00196  * \warning         Decryption with the piecewise API is discouraged, see the
00197  *                  warning on \c mbedtls_chachapoly_init().
00198  *
00199  * \param ctx       The ChaCha20-Poly1305 context. This must be initialized
00200  *                  and bound to a key.
00201  * \param aad_len   The length in Bytes of the AAD. The length has no
00202  *                  restrictions.
00203  * \param aad       Buffer containing the AAD.
00204  *                  This pointer can be \c NULL if `aad_len == 0`.
00205  *
00206  * \return          \c 0 on success.
00207  * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
00208  *                  if \p ctx or \p aad are NULL.
00209  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
00210  *                  if the operations has not been started or has been
00211  *                  finished, or if the AAD has been finished.
00212  */
00213 int mbedtls_chachapoly_update_aad( mbedtls_chachapoly_context *ctx,
00214                                    const unsigned char *aad,
00215                                    size_t aad_len );
00216 
00217 /**
00218  * \brief           Thus function feeds data to be encrypted or decrypted
00219  *                  into an on-going ChaCha20-Poly1305
00220  *                  operation.
00221  *
00222  *                  The direction (encryption or decryption) depends on the
00223  *                  mode that was given when calling
00224  *                  \c mbedtls_chachapoly_starts().
00225  *
00226  *                  You may call this function multiple times to process
00227  *                  an arbitrary amount of data. It is permitted to call
00228  *                  this function 0 times, if no data is to be encrypted
00229  *                  or decrypted.
00230  *
00231  * \warning         Decryption with the piecewise API is discouraged, see the
00232  *                  warning on \c mbedtls_chachapoly_init().
00233  *
00234  * \param ctx       The ChaCha20-Poly1305 context to use. This must be initialized.
00235  * \param len       The length (in bytes) of the data to encrypt or decrypt.
00236  * \param input     The buffer containing the data to encrypt or decrypt.
00237  *                  This pointer can be \c NULL if `len == 0`.
00238  * \param output    The buffer to where the encrypted or decrypted data is
00239  *                  written. This must be able to hold \p len bytes.
00240  *                  This pointer can be \c NULL if `len == 0`.
00241  *
00242  * \return          \c 0 on success.
00243  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
00244  *                  if the operation has not been started or has been
00245  *                  finished.
00246  * \return          Another negative error code on other kinds of failure.
00247  */
00248 int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx,
00249                                size_t len,
00250                                const unsigned char *input,
00251                                unsigned char *output );
00252 
00253 /**
00254  * \brief           This function finished the ChaCha20-Poly1305 operation and
00255  *                  generates the MAC (authentication tag).
00256  *
00257  * \param ctx       The ChaCha20-Poly1305 context to use. This must be initialized.
00258  * \param mac       The buffer to where the 128-bit (16 bytes) MAC is written.
00259  *
00260  * \warning         Decryption with the piecewise API is discouraged, see the
00261  *                  warning on \c mbedtls_chachapoly_init().
00262  *
00263  * \return          \c 0 on success.
00264  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
00265  *                  if the operation has not been started or has been
00266  *                  finished.
00267  * \return          Another negative error code on other kinds of failure.
00268  */
00269 int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx,
00270                                unsigned char mac[16] );
00271 
00272 /**
00273  * \brief           This function performs a complete ChaCha20-Poly1305
00274  *                  authenticated encryption with the previously-set key.
00275  *
00276  * \note            Before using this function, you must set the key with
00277  *                  \c mbedtls_chachapoly_setkey().
00278  *
00279  * \warning         You must never use the same nonce twice with the same key.
00280  *                  This would void any confidentiality and authenticity
00281  *                  guarantees for the messages encrypted with the same nonce
00282  *                  and key.
00283  *
00284  * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
00285  *                  This must be initialized.
00286  * \param length    The length (in bytes) of the data to encrypt or decrypt.
00287  * \param nonce     The 96-bit (12 bytes) nonce/IV to use.
00288  * \param aad       The buffer containing the additional authenticated
00289  *                  data (AAD). This pointer can be \c NULL if `aad_len == 0`.
00290  * \param aad_len   The length (in bytes) of the AAD data to process.
00291  * \param input     The buffer containing the data to encrypt or decrypt.
00292  *                  This pointer can be \c NULL if `ilen == 0`.
00293  * \param output    The buffer to where the encrypted or decrypted data
00294  *                  is written. This pointer can be \c NULL if `ilen == 0`.
00295  * \param tag       The buffer to where the computed 128-bit (16 bytes) MAC
00296  *                  is written. This must not be \c NULL.
00297  *
00298  * \return          \c 0 on success.
00299  * \return          A negative error code on failure.
00300  */
00301 int mbedtls_chachapoly_encrypt_and_tag( mbedtls_chachapoly_context *ctx,
00302                                         size_t length,
00303                                         const unsigned char nonce[12],
00304                                         const unsigned char *aad,
00305                                         size_t aad_len,
00306                                         const unsigned char *input,
00307                                         unsigned char *output,
00308                                         unsigned char tag[16] );
00309 
00310 /**
00311  * \brief           This function performs a complete ChaCha20-Poly1305
00312  *                  authenticated decryption with the previously-set key.
00313  *
00314  * \note            Before using this function, you must set the key with
00315  *                  \c mbedtls_chachapoly_setkey().
00316  *
00317  * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
00318  * \param length    The length (in Bytes) of the data to decrypt.
00319  * \param nonce     The \c 96 Bit (\c 12 bytes) nonce/IV to use.
00320  * \param aad       The buffer containing the additional authenticated data (AAD).
00321  *                  This pointer can be \c NULL if `aad_len == 0`.
00322  * \param aad_len   The length (in bytes) of the AAD data to process.
00323  * \param tag       The buffer holding the authentication tag.
00324  *                  This must be a readable buffer of length \c 16 Bytes.
00325  * \param input     The buffer containing the data to decrypt.
00326  *                  This pointer can be \c NULL if `ilen == 0`.
00327  * \param output    The buffer to where the decrypted data is written.
00328  *                  This pointer can be \c NULL if `ilen == 0`.
00329  *
00330  * \return          \c 0 on success.
00331  * \return          #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
00332  *                  if the data was not authentic.
00333  * \return          Another negative error code on other kinds of failure.
00334  */
00335 int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx,
00336                                      size_t length,
00337                                      const unsigned char nonce[12],
00338                                      const unsigned char *aad,
00339                                      size_t aad_len,
00340                                      const unsigned char tag[16],
00341                                      const unsigned char *input,
00342                                      unsigned char *output );
00343 
00344 #if defined(MBEDTLS_SELF_TEST)
00345 /**
00346  * \brief           The ChaCha20-Poly1305 checkup routine.
00347  *
00348  * \return          \c 0 on success.
00349  * \return          \c 1 on failure.
00350  */
00351 int mbedtls_chachapoly_self_test( int verbose );
00352 #endif /* MBEDTLS_SELF_TEST */
00353 
00354 #ifdef __cplusplus
00355 }
00356 #endif
00357 
00358 #endif /* MBEDTLS_CHACHAPOLY_H */