git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/chachapoly.h

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