common/mbedtls/chachapoly.h

   1 /**
   2  * \file chachapoly.h
   3  *
   4  * \brief   This file contains the AEAD-ChaCha20-Poly1305 definitions and
   5  *          functions.
   6  *
   7  *          ChaCha20-Poly1305 is an algorithm for Authenticated Encryption
   8  *          with Associated Data (AEAD) that can be used to encrypt and
   9  *          authenticate data. It is based on ChaCha20 and Poly1305 by Daniel
  10  *          Bernstein and was standardized 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_CHACHAPOLY_H
  33 #define MBEDTLS_CHACHAPOLY_H
  34
  35 #if !defined(MBEDTLS_CONFIG_FILE)
  36 #include "mbedtls/config.h"
  37 #else
  38 #include MBEDTLS_CONFIG_FILE
  39 #endif
  40
  41 /* for shared error codes */
  42 #include "mbedtls/poly1305.h"
  43
  44 #define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE            -0x0054 /**< The requested operation is not permitted in the current state. */
  45 #define MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED          -0x0056 /**< Authenticated decryption failed: data was not authentic. */
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51 typedef enum {
  52     MBEDTLS_CHACHAPOLY_ENCRYPT,     /**< The mode value for performing encryption. */
  53     MBEDTLS_CHACHAPOLY_DECRYPT      /**< The mode value for performing decryption. */
  54 }
  55 mbedtls_chachapoly_mode_t;
  56
  57 #if !defined(MBEDTLS_CHACHAPOLY_ALT)
  58
  59 #include "mbedtls/chacha20.h"
  60
  61 typedef struct mbedtls_chachapoly_context {
  62     mbedtls_chacha20_context chacha20_ctx;  /**< The ChaCha20 context. */
  63     mbedtls_poly1305_context poly1305_ctx;  /**< The Poly1305 context. */
  64     uint64_t aad_len;                       /**< The length (bytes) of the Additional Authenticated Data. */
  65     uint64_t ciphertext_len;                /**< The length (bytes) of the ciphertext. */
  66     int state;                              /**< The current state of the context. */
  67     mbedtls_chachapoly_mode_t mode;         /**< Cipher mode (encrypt or decrypt). */
  68 }
  69 mbedtls_chachapoly_context;
  70
  71 #else /* !MBEDTLS_CHACHAPOLY_ALT */
  72 #include "chachapoly_alt.h"
  73 #endif /* !MBEDTLS_CHACHAPOLY_ALT */
  74
  75 /**
  76  * \brief           This function initializes the specified ChaCha20-Poly1305 context.
  77  *
  78  *                  It must be the first API called before using
  79  *                  the context. It must be followed by a call to
  80  *                  \c mbedtls_chachapoly_setkey() before any operation can be
  81  *                  done, and to \c mbedtls_chachapoly_free() once all
  82  *                  operations with that context have been finished.
  83  *
  84  *                  In order to encrypt or decrypt full messages at once, for
  85  *                  each message you should make a single call to
  86  *                  \c mbedtls_chachapoly_crypt_and_tag() or
  87  *                  \c mbedtls_chachapoly_auth_decrypt().
  88  *
  89  *                  In order to encrypt messages piecewise, for each
  90  *                  message you should make a call to
  91  *                  \c mbedtls_chachapoly_starts(), then 0 or more calls to
  92  *                  \c mbedtls_chachapoly_update_aad(), then 0 or more calls to
  93  *                  \c mbedtls_chachapoly_update(), then one call to
  94  *                  \c mbedtls_chachapoly_finish().
  95  *
  96  * \warning         Decryption with the piecewise API is discouraged! Always
  97  *                  use \c mbedtls_chachapoly_auth_decrypt() when possible!
  98  *
  99  *                  If however this is not possible because the data is too
 100  *                  large to fit in memory, you need to:
 101  *
 102  *                  - call \c mbedtls_chachapoly_starts() and (if needed)
 103  *                  \c mbedtls_chachapoly_update_aad() as above,
 104  *                  - call \c mbedtls_chachapoly_update() multiple times and
 105  *                  ensure its output (the plaintext) is NOT used in any other
 106  *                  way than placing it in temporary storage at this point,
 107  *                  - call \c mbedtls_chachapoly_finish() to compute the
 108  *                  authentication tag and compared it in constant time to the
 109  *                  tag received with the ciphertext.
 110  *
 111  *                  If the tags are not equal, you must immediately discard
 112  *                  all previous outputs of \c mbedtls_chachapoly_update(),
 113  *                  otherwise you can now safely use the plaintext.
 114  *
 115  * \param ctx       The ChachaPoly context to initialize. Must not be \c NULL.
 116  */
 117 void mbedtls_chachapoly_init(mbedtls_chachapoly_context *ctx);
 118
 119 /**
 120  * \brief           This function releases and clears the specified
 121  *                  ChaCha20-Poly1305 context.
 122  *
 123  * \param ctx       The ChachaPoly context to clear. This may be \c NULL, in which
 124  *                  case this function is a no-op.
 125  */
 126 void mbedtls_chachapoly_free(mbedtls_chachapoly_context *ctx);
 127
 128 /**
 129  * \brief           This function sets the ChaCha20-Poly1305
 130  *                  symmetric encryption key.
 131  *
 132  * \param ctx       The ChaCha20-Poly1305 context to which the key should be
 133  *                  bound. This must be initialized.
 134  * \param key       The \c 256 Bit (\c 32 Bytes) key.
 135  *
 136  * \return          \c 0 on success.
 137  * \return          A negative error code on failure.
 138  */
 139 int mbedtls_chachapoly_setkey(mbedtls_chachapoly_context *ctx,
 140                               const unsigned char key[32]);
 141
 142 /**
 143  * \brief           This function starts a ChaCha20-Poly1305 encryption or
 144  *                  decryption operation.
 145  *
 146  * \warning         You must never use the same nonce twice with the same key.
 147  *                  This would void any confidentiality and authenticity
 148  *                  guarantees for the messages encrypted with the same nonce
 149  *                  and key.
 150  *
 151  * \note            If the context is being used for AAD only (no data to
 152  *                  encrypt or decrypt) then \p mode can be set to any value.
 153  *
 154  * \warning         Decryption with the piecewise API is discouraged, see the
 155  *                  warning on \c mbedtls_chachapoly_init().
 156  *
 157  * \param ctx       The ChaCha20-Poly1305 context. This must be initialized
 158  *                  and bound to a key.
 159  * \param nonce     The nonce/IV to use for the message.
 160  *                  This must be a redable buffer of length \c 12 Bytes.
 161  * \param mode      The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
 162  *                  #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).
 163  *
 164  * \return          \c 0 on success.
 165  * \return          A negative error code on failure.
 166  */
 167 int mbedtls_chachapoly_starts(mbedtls_chachapoly_context *ctx,
 168                               const unsigned char nonce[12],
 169                               mbedtls_chachapoly_mode_t mode);
 170
 171 /**
 172  * \brief           This function feeds additional data to be authenticated
 173  *                  into an ongoing ChaCha20-Poly1305 operation.
 174  *
 175  *                  The Additional Authenticated Data (AAD), also called
 176  *                  Associated Data (AD) is only authenticated but not
 177  *                  encrypted nor included in the encrypted output. It is
 178  *                  usually transmitted separately from the ciphertext or
 179  *                  computed locally by each party.
 180  *
 181  * \note            This function is called before data is encrypted/decrypted.
 182  *                  I.e. call this function to process the AAD before calling
 183  *                  \c mbedtls_chachapoly_update().
 184  *
 185  *                  You may call this function multiple times to process
 186  *                  an arbitrary amount of AAD. It is permitted to call
 187  *                  this function 0 times, if no AAD is used.
 188  *
 189  *                  This function cannot be called any more if data has
 190  *                  been processed by \c mbedtls_chachapoly_update(),
 191  *                  or if the context has been finished.
 192  *
 193  * \warning         Decryption with the piecewise API is discouraged, see the
 194  *                  warning on \c mbedtls_chachapoly_init().
 195  *
 196  * \param ctx       The ChaCha20-Poly1305 context. This must be initialized
 197  *                  and bound to a key.
 198  * \param aad_len   The length in Bytes of the AAD. The length has no
 199  *                  restrictions.
 200  * \param aad       Buffer containing the AAD.
 201  *                  This pointer can be \c NULL if `aad_len == 0`.
 202  *
 203  * \return          \c 0 on success.
 204  * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
 205  *                  if \p ctx or \p aad are NULL.
 206  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
 207  *                  if the operations has not been started or has been
 208  *                  finished, or if the AAD has been finished.
 209  */
 210 int mbedtls_chachapoly_update_aad(mbedtls_chachapoly_context *ctx,
 211                                   const unsigned char *aad,
 212                                   size_t aad_len);
 213
 214 /**
 215  * \brief           Thus function feeds data to be encrypted or decrypted
 216  *                  into an on-going ChaCha20-Poly1305
 217  *                  operation.
 218  *
 219  *                  The direction (encryption or decryption) depends on the
 220  *                  mode that was given when calling
 221  *                  \c mbedtls_chachapoly_starts().
 222  *
 223  *                  You may call this function multiple times to process
 224  *                  an arbitrary amount of data. It is permitted to call
 225  *                  this function 0 times, if no data is to be encrypted
 226  *                  or decrypted.
 227  *
 228  * \warning         Decryption with the piecewise API is discouraged, see the
 229  *                  warning on \c mbedtls_chachapoly_init().
 230  *
 231  * \param ctx       The ChaCha20-Poly1305 context to use. This must be initialized.
 232  * \param len       The length (in bytes) of the data to encrypt or decrypt.
 233  * \param input     The buffer containing the data to encrypt or decrypt.
 234  *                  This pointer can be \c NULL if `len == 0`.
 235  * \param output    The buffer to where the encrypted or decrypted data is
 236  *                  written. This must be able to hold \p len bytes.
 237  *                  This pointer can be \c NULL if `len == 0`.
 238  *
 239  * \return          \c 0 on success.
 240  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
 241  *                  if the operation has not been started or has been
 242  *                  finished.
 243  * \return          Another negative error code on other kinds of failure.
 244  */
 245 int mbedtls_chachapoly_update(mbedtls_chachapoly_context *ctx,
 246                               size_t len,
 247                               const unsigned char *input,
 248                               unsigned char *output);
 249
 250 /**
 251  * \brief           This function finished the ChaCha20-Poly1305 operation and
 252  *                  generates the MAC (authentication tag).
 253  *
 254  * \param ctx       The ChaCha20-Poly1305 context to use. This must be initialized.
 255  * \param mac       The buffer to where the 128-bit (16 bytes) MAC is written.
 256  *
 257  * \warning         Decryption with the piecewise API is discouraged, see the
 258  *                  warning on \c mbedtls_chachapoly_init().
 259  *
 260  * \return          \c 0 on success.
 261  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
 262  *                  if the operation has not been started or has been
 263  *                  finished.
 264  * \return          Another negative error code on other kinds of failure.
 265  */
 266 int mbedtls_chachapoly_finish(mbedtls_chachapoly_context *ctx,
 267                               unsigned char mac[16]);
 268
 269 /**
 270  * \brief           This function performs a complete ChaCha20-Poly1305
 271  *                  authenticated encryption with the previously-set key.
 272  *
 273  * \note            Before using this function, you must set the key with
 274  *                  \c mbedtls_chachapoly_setkey().
 275  *
 276  * \warning         You must never use the same nonce twice with the same key.
 277  *                  This would void any confidentiality and authenticity
 278  *                  guarantees for the messages encrypted with the same nonce
 279  *                  and key.
 280  *
 281  * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
 282  *                  This must be initialized.
 283  * \param length    The length (in bytes) of the data to encrypt or decrypt.
 284  * \param nonce     The 96-bit (12 bytes) nonce/IV to use.
 285  * \param aad       The buffer containing the additional authenticated
 286  *                  data (AAD). This pointer can be \c NULL if `aad_len == 0`.
 287  * \param aad_len   The length (in bytes) of the AAD data to process.
 288  * \param input     The buffer containing the data to encrypt or decrypt.
 289  *                  This pointer can be \c NULL if `ilen == 0`.
 290  * \param output    The buffer to where the encrypted or decrypted data
 291  *                  is written. This pointer can be \c NULL if `ilen == 0`.
 292  * \param tag       The buffer to where the computed 128-bit (16 bytes) MAC
 293  *                  is written. This must not be \c NULL.
 294  *
 295  * \return          \c 0 on success.
 296  * \return          A negative error code on failure.
 297  */
 298 int mbedtls_chachapoly_encrypt_and_tag(mbedtls_chachapoly_context *ctx,
 299                                        size_t length,
 300                                        const unsigned char nonce[12],
 301                                        const unsigned char *aad,
 302                                        size_t aad_len,
 303                                        const unsigned char *input,
 304                                        unsigned char *output,
 305                                        unsigned char tag[16]);
 306
 307 /**
 308  * \brief           This function performs a complete ChaCha20-Poly1305
 309  *                  authenticated decryption with the previously-set key.
 310  *
 311  * \note            Before using this function, you must set the key with
 312  *                  \c mbedtls_chachapoly_setkey().
 313  *
 314  * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
 315  * \param length    The length (in Bytes) of the data to decrypt.
 316  * \param nonce     The \c 96 Bit (\c 12 bytes) nonce/IV to use.
 317  * \param aad       The buffer containing the additional authenticated data (AAD).
 318  *                  This pointer can be \c NULL if `aad_len == 0`.
 319  * \param aad_len   The length (in bytes) of the AAD data to process.
 320  * \param tag       The buffer holding the authentication tag.
 321  *                  This must be a readable buffer of length \c 16 Bytes.
 322  * \param input     The buffer containing the data to decrypt.
 323  *                  This pointer can be \c NULL if `ilen == 0`.
 324  * \param output    The buffer to where the decrypted data is written.
 325  *                  This pointer can be \c NULL if `ilen == 0`.
 326  *
 327  * \return          \c 0 on success.
 328  * \return          #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
 329  *                  if the data was not authentic.
 330  * \return          Another negative error code on other kinds of failure.
 331  */
 332 int mbedtls_chachapoly_auth_decrypt(mbedtls_chachapoly_context *ctx,
 333                                     size_t length,
 334                                     const unsigned char nonce[12],
 335                                     const unsigned char *aad,
 336                                     size_t aad_len,
 337                                     const unsigned char tag[16],
 338                                     const unsigned char *input,
 339                                     unsigned char *output);
 340
 341 #if defined(MBEDTLS_SELF_TEST)
 342 /**
 343  * \brief           The ChaCha20-Poly1305 checkup routine.
 344  *
 345  * \return          \c 0 on success.
 346  * \return          \c 1 on failure.
 347  */
 348 int mbedtls_chachapoly_self_test(int verbose);
 349 #endif /* MBEDTLS_SELF_TEST */
 350
 351 #ifdef __cplusplus
 352 }
 353 #endif
 354
 355 #endif /* MBEDTLS_CHACHAPOLY_H */