mbedtls/private/chachapoly.h

0001 /**
0002  * \file chachapoly.h
0003  *
0004  * \brief   This file contains the AEAD-ChaCha20-Poly1305 definitions and
0005  *          functions.
0006  *
0007  *          ChaCha20-Poly1305 is an algorithm for Authenticated Encryption
0008  *          with Associated Data (AEAD) that can be used to encrypt and
0009  *          authenticate data. It is based on ChaCha20 and Poly1305 by Daniel
0010  *          Bernstein and was standardized in RFC 7539.
0011  *
0012  * \author Daniel King <damaki.gh@gmail.com>
0013  */
0014
0015 /*
0016  *  Copyright The Mbed TLS Contributors
0017  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0018  */
0019
0020 #ifndef MBEDTLS_CHACHAPOLY_H
0021 #define MBEDTLS_CHACHAPOLY_H
0022 #include "mbedtls/private_access.h"
0023
0024 #include "tf-psa-crypto/build_info.h"
0025
0026 /* for shared error codes */
0027 #include "mbedtls/private/poly1305.h"
0028
0029 /** The requested operation is not permitted in the current state. */
0030 #define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE            -0x0054
0031 /** Authenticated decryption failed: data was not authentic. */
0032 #define MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED          PSA_ERROR_INVALID_SIGNATURE
0033
0034 #ifdef __cplusplus
0035 extern "C" {
0036 #endif
0037
0038 typedef enum {
0039     MBEDTLS_CHACHAPOLY_ENCRYPT,     /**< The mode value for performing encryption. */
0040     MBEDTLS_CHACHAPOLY_DECRYPT      /**< The mode value for performing decryption. */
0041 }
0042 mbedtls_chachapoly_mode_t;
0043
0044 #include "mbedtls/private/chacha20.h"
0045
0046 typedef struct mbedtls_chachapoly_context {
0047     mbedtls_chacha20_context MBEDTLS_PRIVATE(chacha20_ctx);  /**< The ChaCha20 context. */
0048     mbedtls_poly1305_context MBEDTLS_PRIVATE(poly1305_ctx);  /**< The Poly1305 context. */
0049     uint64_t MBEDTLS_PRIVATE(aad_len);                       /**< The length (bytes) of the Additional Authenticated Data. */
0050     uint64_t MBEDTLS_PRIVATE(ciphertext_len);                /**< The length (bytes) of the ciphertext. */
0051     int MBEDTLS_PRIVATE(state);                              /**< The current state of the context. */
0052     mbedtls_chachapoly_mode_t MBEDTLS_PRIVATE(mode);         /**< Cipher mode (encrypt or decrypt). */
0053 }
0054 mbedtls_chachapoly_context;
0055
0056 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
0057 /**
0058  * \brief           This function initializes the specified ChaCha20-Poly1305 context.
0059  *
0060  *                  It must be the first API called before using
0061  *                  the context. It must be followed by a call to
0062  *                  \c mbedtls_chachapoly_setkey() before any operation can be
0063  *                  done, and to \c mbedtls_chachapoly_free() once all
0064  *                  operations with that context have been finished.
0065  *
0066  *                  In order to encrypt or decrypt full messages at once, for
0067  *                  each message you should make a single call to
0068  *                  \c mbedtls_chachapoly_crypt_and_tag() or
0069  *                  \c mbedtls_chachapoly_auth_decrypt().
0070  *
0071  *                  In order to encrypt messages piecewise, for each
0072  *                  message you should make a call to
0073  *                  \c mbedtls_chachapoly_starts(), then 0 or more calls to
0074  *                  \c mbedtls_chachapoly_update_aad(), then 0 or more calls to
0075  *                  \c mbedtls_chachapoly_update(), then one call to
0076  *                  \c mbedtls_chachapoly_finish().
0077  *
0078  * \warning         Decryption with the piecewise API is discouraged! Always
0079  *                  use \c mbedtls_chachapoly_auth_decrypt() when possible!
0080  *
0081  *                  If however this is not possible because the data is too
0082  *                  large to fit in memory, you need to:
0083  *
0084  *                  - call \c mbedtls_chachapoly_starts() and (if needed)
0085  *                  \c mbedtls_chachapoly_update_aad() as above,
0086  *                  - call \c mbedtls_chachapoly_update() multiple times and
0087  *                  ensure its output (the plaintext) is NOT used in any other
0088  *                  way than placing it in temporary storage at this point,
0089  *                  - call \c mbedtls_chachapoly_finish() to compute the
0090  *                  authentication tag and compared it in constant time to the
0091  *                  tag received with the ciphertext.
0092  *
0093  *                  If the tags are not equal, you must immediately discard
0094  *                  all previous outputs of \c mbedtls_chachapoly_update(),
0095  *                  otherwise you can now safely use the plaintext.
0096  *
0097  * \param ctx       The ChachaPoly context to initialize. Must not be \c NULL.
0098  */
0099 void mbedtls_chachapoly_init(mbedtls_chachapoly_context *ctx);
0100
0101 /**
0102  * \brief           This function releases and clears the specified
0103  *                  ChaCha20-Poly1305 context.
0104  *
0105  * \param ctx       The ChachaPoly context to clear. This may be \c NULL, in which
0106  *                  case this function is a no-op.
0107  */
0108 void mbedtls_chachapoly_free(mbedtls_chachapoly_context *ctx);
0109
0110 /**
0111  * \brief           This function sets the ChaCha20-Poly1305
0112  *                  symmetric encryption key.
0113  *
0114  * \param ctx       The ChaCha20-Poly1305 context to which the key should be
0115  *                  bound. This must be initialized.
0116  * \param key       The \c 256 Bit (\c 32 Bytes) key.
0117  *
0118  * \return          \c 0 on success.
0119  * \return          A negative error code on failure.
0120  */
0121 int mbedtls_chachapoly_setkey(mbedtls_chachapoly_context *ctx,
0122                               const unsigned char key[32]);
0123
0124 /**
0125  * \brief           This function starts a ChaCha20-Poly1305 encryption or
0126  *                  decryption operation.
0127  *
0128  * \warning         You must never use the same nonce twice with the same key.
0129  *                  This would void any confidentiality and authenticity
0130  *                  guarantees for the messages encrypted with the same nonce
0131  *                  and key.
0132  *
0133  * \note            If the context is being used for AAD only (no data to
0134  *                  encrypt or decrypt) then \p mode can be set to any value.
0135  *
0136  * \warning         Decryption with the piecewise API is discouraged, see the
0137  *                  warning on \c mbedtls_chachapoly_init().
0138  *
0139  * \param ctx       The ChaCha20-Poly1305 context. This must be initialized
0140  *                  and bound to a key.
0141  * \param nonce     The nonce/IV to use for the message.
0142  *                  This must be a readable buffer of length \c 12 Bytes.
0143  * \param mode      The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
0144  *                  #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).
0145  *
0146  * \return          \c 0 on success.
0147  * \return          A negative error code on failure.
0148  */
0149 int mbedtls_chachapoly_starts(mbedtls_chachapoly_context *ctx,
0150                               const unsigned char nonce[12],
0151                               mbedtls_chachapoly_mode_t mode);
0152
0153 /**
0154  * \brief           This function feeds additional data to be authenticated
0155  *                  into an ongoing ChaCha20-Poly1305 operation.
0156  *
0157  *                  The Additional Authenticated Data (AAD), also called
0158  *                  Associated Data (AD) is only authenticated but not
0159  *                  encrypted nor included in the encrypted output. It is
0160  *                  usually transmitted separately from the ciphertext or
0161  *                  computed locally by each party.
0162  *
0163  * \note            This function is called before data is encrypted/decrypted.
0164  *                  I.e. call this function to process the AAD before calling
0165  *                  \c mbedtls_chachapoly_update().
0166  *
0167  *                  You may call this function multiple times to process
0168  *                  an arbitrary amount of AAD. It is permitted to call
0169  *                  this function 0 times, if no AAD is used.
0170  *
0171  *                  This function cannot be called any more if data has
0172  *                  been processed by \c mbedtls_chachapoly_update(),
0173  *                  or if the context has been finished.
0174  *
0175  * \warning         Decryption with the piecewise API is discouraged, see the
0176  *                  warning on \c mbedtls_chachapoly_init().
0177  *
0178  * \param ctx       The ChaCha20-Poly1305 context. This must be initialized
0179  *                  and bound to a key.
0180  * \param aad_len   The length in Bytes of the AAD. The length has no
0181  *                  restrictions.
0182  * \param aad       Buffer containing the AAD.
0183  *                  This pointer can be \c NULL if `aad_len == 0`.
0184  *
0185  * \return          \c 0 on success.
0186  * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
0187  *                  if \p ctx or \p aad are NULL.
0188  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
0189  *                  if the operations has not been started or has been
0190  *                  finished, or if the AAD has been finished.
0191  */
0192 int mbedtls_chachapoly_update_aad(mbedtls_chachapoly_context *ctx,
0193                                   const unsigned char *aad,
0194                                   size_t aad_len);
0195
0196 /**
0197  * \brief           Thus function feeds data to be encrypted or decrypted
0198  *                  into an on-going ChaCha20-Poly1305
0199  *                  operation.
0200  *
0201  *                  The direction (encryption or decryption) depends on the
0202  *                  mode that was given when calling
0203  *                  \c mbedtls_chachapoly_starts().
0204  *
0205  *                  You may call this function multiple times to process
0206  *                  an arbitrary amount of data. It is permitted to call
0207  *                  this function 0 times, if no data is to be encrypted
0208  *                  or decrypted.
0209  *
0210  * \warning         Decryption with the piecewise API is discouraged, see the
0211  *                  warning on \c mbedtls_chachapoly_init().
0212  *
0213  * \param ctx       The ChaCha20-Poly1305 context to use. This must be initialized.
0214  * \param len       The length (in bytes) of the data to encrypt or decrypt.
0215  * \param input     The buffer containing the data to encrypt or decrypt.
0216  *                  This pointer can be \c NULL if `len == 0`.
0217  * \param output    The buffer to where the encrypted or decrypted data is
0218  *                  written. This must be able to hold \p len bytes.
0219  *                  This pointer can be \c NULL if `len == 0`.
0220  *
0221  * \return          \c 0 on success.
0222  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
0223  *                  if the operation has not been started or has been
0224  *                  finished.
0225  * \return          Another negative error code on other kinds of failure.
0226  */
0227 int mbedtls_chachapoly_update(mbedtls_chachapoly_context *ctx,
0228                               size_t len,
0229                               const unsigned char *input,
0230                               unsigned char *output);
0231
0232 /**
0233  * \brief           This function finished the ChaCha20-Poly1305 operation and
0234  *                  generates the MAC (authentication tag).
0235  *
0236  * \param ctx       The ChaCha20-Poly1305 context to use. This must be initialized.
0237  * \param mac       The buffer to where the 128-bit (16 bytes) MAC is written.
0238  *
0239  * \warning         Decryption with the piecewise API is discouraged, see the
0240  *                  warning on \c mbedtls_chachapoly_init().
0241  *
0242  * \return          \c 0 on success.
0243  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
0244  *                  if the operation has not been started or has been
0245  *                  finished.
0246  * \return          Another negative error code on other kinds of failure.
0247  */
0248 int mbedtls_chachapoly_finish(mbedtls_chachapoly_context *ctx,
0249                               unsigned char mac[16]);
0250
0251 /**
0252  * \brief           This function performs a complete ChaCha20-Poly1305
0253  *                  authenticated encryption with the previously-set key.
0254  *
0255  * \note            Before using this function, you must set the key with
0256  *                  \c mbedtls_chachapoly_setkey().
0257  *
0258  * \warning         You must never use the same nonce twice with the same key.
0259  *                  This would void any confidentiality and authenticity
0260  *                  guarantees for the messages encrypted with the same nonce
0261  *                  and key.
0262  *
0263  * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
0264  *                  This must be initialized.
0265  * \param length    The length (in bytes) of the data to encrypt or decrypt.
0266  * \param nonce     The 96-bit (12 bytes) nonce/IV to use.
0267  * \param aad       The buffer containing the additional authenticated
0268  *                  data (AAD). This pointer can be \c NULL if `aad_len == 0`.
0269  * \param aad_len   The length (in bytes) of the AAD data to process.
0270  * \param input     The buffer containing the data to encrypt or decrypt.
0271  *                  This pointer can be \c NULL if `ilen == 0`.
0272  * \param output    The buffer to where the encrypted or decrypted data
0273  *                  is written. This pointer can be \c NULL if `ilen == 0`.
0274  * \param tag       The buffer to where the computed 128-bit (16 bytes) MAC
0275  *                  is written. This must not be \c NULL.
0276  *
0277  * \return          \c 0 on success.
0278  * \return          A negative error code on failure.
0279  */
0280 int mbedtls_chachapoly_encrypt_and_tag(mbedtls_chachapoly_context *ctx,
0281                                        size_t length,
0282                                        const unsigned char nonce[12],
0283                                        const unsigned char *aad,
0284                                        size_t aad_len,
0285                                        const unsigned char *input,
0286                                        unsigned char *output,
0287                                        unsigned char tag[16]);
0288
0289 /**
0290  * \brief           This function performs a complete ChaCha20-Poly1305
0291  *                  authenticated decryption with the previously-set key.
0292  *
0293  * \note            Before using this function, you must set the key with
0294  *                  \c mbedtls_chachapoly_setkey().
0295  *
0296  * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
0297  * \param length    The length (in Bytes) of the data to decrypt.
0298  * \param nonce     The \c 96 Bit (\c 12 bytes) nonce/IV to use.
0299  * \param aad       The buffer containing the additional authenticated data (AAD).
0300  *                  This pointer can be \c NULL if `aad_len == 0`.
0301  * \param aad_len   The length (in bytes) of the AAD data to process.
0302  * \param tag       The buffer holding the authentication tag.
0303  *                  This must be a readable buffer of length \c 16 Bytes.
0304  * \param input     The buffer containing the data to decrypt.
0305  *                  This pointer can be \c NULL if `ilen == 0`.
0306  * \param output    The buffer to where the decrypted data is written.
0307  *                  This pointer can be \c NULL if `ilen == 0`.
0308  *
0309  * \return          \c 0 on success.
0310  * \return          #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
0311  *                  if the data was not authentic.
0312  * \return          Another negative error code on other kinds of failure.
0313  */
0314 int mbedtls_chachapoly_auth_decrypt(mbedtls_chachapoly_context *ctx,
0315                                     size_t length,
0316                                     const unsigned char nonce[12],
0317                                     const unsigned char *aad,
0318                                     size_t aad_len,
0319                                     const unsigned char tag[16],
0320                                     const unsigned char *input,
0321                                     unsigned char *output);
0322
0323 #if defined(MBEDTLS_SELF_TEST)
0324 /**
0325  * \brief           The ChaCha20-Poly1305 checkup routine.
0326  *
0327  * \return          \c 0 on success.
0328  * \return          \c 1 on failure.
0329  */
0330 int mbedtls_chachapoly_self_test(int verbose);
0331 #endif /* MBEDTLS_SELF_TEST */
0332
0333 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */
0334
0335 #ifdef __cplusplus
0336 }
0337 #endif
0338
0339 #endif /* MBEDTLS_CHACHAPOLY_H */