src/third_party/boringssl/src/include/openssl/aead.h

   1 /* Copyright (c) 2014, Google Inc.
   2  *
   3  * Permission to use, copy, modify, and/or distribute this software for any
   4  * purpose with or without fee is hereby granted, provided that the above
   5  * copyright notice and this permission notice appear in all copies.
   6  *
   7  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   8  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   9  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  10  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  11  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  12  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  13  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
  14
  15 #ifndef OPENSSL_HEADER_AEAD_H
  16 #define OPENSSL_HEADER_AEAD_H
  17
  18 #include <openssl/base.h>
  19
  20 #if defined(__cplusplus)
  21 extern "C" {
  22 #endif
  23
  24
  25 /* Authenticated Encryption with Additional Data.
  26  *
  27  * AEAD couples confidentiality and integrity in a single primtive. AEAD
  28  * algorithms take a key and then can seal and open individual messages. Each
  29  * message has a unique, per-message nonce and, optionally, additional data
  30  * which is authenticated but not included in the ciphertext.
  31  *
  32  * The |EVP_AEAD_CTX_init| function initialises an |EVP_AEAD_CTX| structure and
  33  * performs any precomputation needed to use |aead| with |key|. The length of
  34  * the key, |key_len|, is given in bytes.
  35  *
  36  * The |tag_len| argument contains the length of the tags, in bytes, and allows
  37  * for the processing of truncated authenticators. A zero value indicates that
  38  * the default tag length should be used and this is defined as
  39  * |EVP_AEAD_DEFAULT_TAG_LENGTH| in order to make the code clear. Using
  40  * truncated tags increases an attacker's chance of creating a valid forgery.
  41  * Be aware that the attacker's chance may increase more than exponentially as
  42  * would naively be expected.
  43  *
  44  * When no longer needed, the initialised |EVP_AEAD_CTX| structure must be
  45  * passed to |EVP_AEAD_CTX_cleanup|, which will deallocate any memory used.
  46  *
  47  * With an |EVP_AEAD_CTX| in hand, one can seal and open messages. These
  48  * operations are intended to meet the standard notions of privacy and
  49  * authenticity for authenticated encryption. For formal definitions see
  50  * Bellare and Namprempre, "Authenticated encryption: relations among notions
  51  * and analysis of the generic composition paradigm," Lecture Notes in Computer
  52  * Science B<1976> (2000), 531–545,
  53  * http://www-cse.ucsd.edu/~mihir/papers/oem.html.
  54  *
  55  * When sealing messages, a nonce must be given. The length of the nonce is
  56  * fixed by the AEAD in use and is returned by |EVP_AEAD_nonce_length|. *The
  57  * nonce must be unique for all messages with the same key*. This is critically
  58  * important - nonce reuse may completely undermine the security of the AEAD.
  59  * Nonces may be predictable and public, so long as they are unique. Uniqueness
  60  * may be achieved with a simple counter or, if large enough, may be generated
  61  * randomly. The nonce must be passed into the "open" operation by the receiver
  62  * so must either be implicit (e.g. a counter), or must be transmitted along
  63  * with the sealed message.
  64  *
  65  * The "seal" and "open" operations are atomic - an entire message must be
  66  * encrypted or decrypted in a single call. Large messages may have to be split
  67  * up in order to accomodate this. When doing so, be mindful of the need not to
  68  * repeat nonces and the possibility that an attacker could duplicate, reorder
  69  * or drop message chunks. For example, using a single key for a given (large)
  70  * message and sealing chunks with nonces counting from zero would be secure as
  71  * long as the number of chunks was securely transmitted. (Otherwise an
  72  * attacker could truncate the message by dropping chunks from the end.)
  73  *
  74  * The number of chunks could be transmitted by prefixing it to the plaintext,
  75  * for example. This also assumes that no other message would ever use the same
  76  * key otherwise the rule that nonces must be unique for a given key would be
  77  * violated.
  78  *
  79  * The "seal" and "open" operations also permit additional data to be
  80  * authenticated via the |ad| parameter. This data is not included in the
  81  * ciphertext and must be identical for both the "seal" and "open" call. This
  82  * permits implicit context to be authenticated but may be empty if not needed.
  83  *
  84  * The "seal" and "open" operations may work in-place if the |out| and |in|
  85  * arguments are equal. They may also be used to shift the data left inside the
  86  * same buffer if |out| is less than |in|. However, |out| may not point inside
  87  * the input data otherwise the input may be overwritten before it has been
  88  * read. This situation will cause an error.
  89  *
  90  * The "seal" and "open" operations return one on success and zero on error. */
  91
  92
  93 /* AEAD algorithms. */
  94
  95 /* EVP_aes_128_gcm is AES-128 in Galois Counter Mode. */
  96 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm(void);
  97
  98 /* EVP_aes_256_gcm is AES-256 in Galois Counter Mode. */
  99 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm(void);
 100
 101 /* EVP_aead_chacha20_poly1305 is an AEAD built from ChaCha20 and Poly1305. */
 102 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305();
 103
 104 /* EVP_aead_aes_128_key_wrap is AES-128 Key Wrap mode. This should never be
 105  * used except to interoperate with existing systems that use this mode.
 106  *
 107  * If the nonce is emtpy then the default nonce will be used, otherwise it must
 108  * be eight bytes long. The input must be a multiple of eight bytes long. No
 109  * additional data can be given to this mode. */
 110 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_key_wrap();
 111
 112 /* EVP_aead_aes_256_key_wrap is AES-256 in Key Wrap mode. This should never be
 113  * used except to interoperate with existing systems that use this mode.
 114  *
 115  * See |EVP_aead_aes_128_key_wrap| for details. */
 116 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_key_wrap();
 117
 118
 119 /* TLS specific AEAD algorithms.
 120  *
 121  * These AEAD primitives do not meet the definition of generic AEADs. They are
 122  * all specific to TLS in some fashion and should not be used outside of that
 123  * context. */
 124
 125 /* EVP_aead_rc4_md5_tls uses RC4 and HMAC(MD5) in MAC-then-encrypt mode. Unlike
 126  * a standard AEAD, this is stateful as the RC4 state is carried from operation
 127  * to operation. */
 128 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_md5_tls();
 129
 130
 131 /* Utility functions. */
 132
 133 /* EVP_AEAD_key_length returns the length, in bytes, of the keys used by
 134  * |aead|. */
 135 OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead);
 136
 137 /* EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce
 138  * for |aead|. */
 139 OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead);
 140
 141 /* EVP_AEAD_max_overhead returns the maximum number of additional bytes added
 142  * by the act of sealing data with |aead|. */
 143 OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead);
 144
 145 /* EVP_AEAD_max_tag_len returns the maximum tag length when using |aead|. This
 146  * is the largest value that can be passed as |tag_len| to
 147  * |EVP_AEAD_CTX_init|. */
 148 OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead);
 149
 150
 151 /* AEAD operations. */
 152
 153 /* An EVP_AEAD_CTX represents an AEAD algorithm configured with a specific key
 154  * and message-independent IV. */
 155 typedef struct evp_aead_ctx_st {
 156   const EVP_AEAD *aead;
 157   /* aead_state is an opaque pointer to whatever state the AEAD needs to
 158    * maintain. */
 159   void *aead_state;
 160 } EVP_AEAD_CTX;
 161
 162 /* EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD
 163  * defined in this header. */
 164 #define EVP_AEAD_MAX_OVERHEAD 16
 165
 166 /* EVP_AEAD_DEFAULT_TAG_LENGTH is a magic value that can be passed to
 167  * EVP_AEAD_CTX_init to indicate that the default tag length for an AEAD should
 168  * be used. */
 169 #define EVP_AEAD_DEFAULT_TAG_LENGTH 0
 170
 171 /* EVP_AEAD_init initializes |ctx| for the given AEAD algorithm from |impl|.
 172  * The |impl| argument may be NULL to choose the default implementation.
 173  * Authentication tags may be truncated by passing a size as |tag_len|. A
 174  * |tag_len| of zero indicates the default tag length and this is defined as
 175  * EVP_AEAD_DEFAULT_TAG_LENGTH for readability.
 176  * Returns 1 on success. Otherwise returns 0 and pushes to the error stack. */
 177 OPENSSL_EXPORT int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead,
 178                                      const uint8_t *key, size_t key_len,
 179                                      size_t tag_len, ENGINE *impl);
 180
 181 /* EVP_AEAD_CTX_cleanup frees any data allocated by |ctx|. */
 182 OPENSSL_EXPORT void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx);
 183
 184 /* EVP_AEAD_CTX_seal encrypts and authenticates |in_len| bytes from |in| and
 185  * authenticates |ad_len| bytes from |ad| and writes the result to |out|. It
 186  * returns one on success and zero otherwise.
 187  *
 188  * This function may be called (with the same |EVP_AEAD_CTX|) concurrently with
 189  * itself or |EVP_AEAD_CTX_open|.
 190  *
 191  * At most |max_out_len| bytes are written to |out| and, in order to ensure
 192  * success, |max_out_len| should be |in_len| plus the result of
 193  * |EVP_AEAD_overhead|. On successful return, |*out_len| is set to the actual
 194  * number of bytes written.
 195  *
 196  * The length of |nonce|, |nonce_len|, must be equal to the result of
 197  * |EVP_AEAD_nonce_length| for this AEAD.
 198  *
 199  * |EVP_AEAD_CTX_seal| never results in a partial output. If |max_out_len| is
 200  * insufficient, zero will be returned. (In this case, |*out_len| is set to
 201  * zero.)
 202  *
 203  * If |in| and |out| alias then |out| must be <= |in|. */
 204 OPENSSL_EXPORT int EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx, uint8_t *out,
 205                                      size_t *out_len, size_t max_out_len,
 206                                      const uint8_t *nonce, size_t nonce_len,
 207                                      const uint8_t *in, size_t in_len,
 208                                      const uint8_t *ad, size_t ad_len);
 209
 210 /* EVP_AEAD_CTX_open authenticates |in_len| bytes from |in| and |ad_len| bytes
 211  * from |ad| and decrypts at most |in_len| bytes into |out|. It returns one on
 212  * success and zero otherwise.
 213  *
 214  * This function may be called (with the same |EVP_AEAD_CTX|) concurrently with
 215  * itself or |EVP_AEAD_CTX_seal|.
 216  *
 217  * At most |in_len| bytes are written to |out|. In order to ensure success,
 218  * |max_out_len| should be at least |in_len|. On successful return, |*out_len|
 219  * is set to the the actual number of bytes written.
 220  *
 221  * The length of |nonce|, |nonce_len|, must be equal to the result of
 222  * |EVP_AEAD_nonce_length| for this AEAD.
 223  *
 224  * |EVP_AEAD_CTX_open| never results in a partial output. If |max_out_len| is
 225  * insufficient, zero will be returned. (In this case, |*out_len| is set to
 226  * zero.)
 227  *
 228  * If |in| and |out| alias then |out| must be <= |in|. */
 229 OPENSSL_EXPORT int EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, uint8_t *out,
 230                                      size_t *out_len, size_t max_out_len,
 231                                      const uint8_t *nonce, size_t nonce_len,
 232                                      const uint8_t *in, size_t in_len,
 233                                      const uint8_t *ad, size_t ad_len);
 234
 235
 236 #if defined(__cplusplus)
 237 }  /* extern C */
 238 #endif
 239
 240 #endif  /* OPENSSL_HEADER_AEAD_H */