doc/crypto/EVP_AEAD_CTX_init.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_AEAD_CTX_init, EVP_AEAD_CTX_cleanup, EVP_AEAD_CTX_seal, EVP_AEAD_CTX_open - authenticated encryption functions.
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/evp.h>
  10
  11  int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead,
  12                        const unsigned char *key, size_t key_len,
  13                        size_t tag_len, ENGINE *impl);
  14  void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx);
  15  ssize_t EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx,
  16                            unsigned char *out, size_t max_out_len,
  17                            const unsigned char *nonce, size_t nonce_len,
  18                            const unsigned char *in, size_t in_len,
  19                            const unsigned char *ad, size_t ad_len);
  20  ssize_t EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx,
  21                            unsigned char *out, size_t max_out_len,
  22                            const unsigned char *nonce, size_t nonce_len,
  23                            const unsigned char *in, size_t in_len,
  24                            const unsigned char *ad, size_t ad_len);
  25
  26 =head1 DESCRIPTION
  27
  28 The EVP_AEAD_CTX_init() function initialises an B<EVP_AEAD_CTX> structure and
  29 performs any precomputation needed to use B<aead> with B<key>. The length of
  30 the key, B<key_len>, is given in bytes.
  31
  32 The B<tag_len> argument contains the length of the tags, in bytes, and allows
  33 for the processing of truncated authenticators. A zero value indicates that the
  34 default tag length should be used and this is defined as
  35 C<EVP_AEAD_DEFAULT_TAG_LENGTH> in order to make the code clear. Using truncated
  36 tags increases an attacker's chance of creating a valid forgery. Be aware that
  37 the attacker's chance may increase more than exponentially as would naively be
  38 expected.
  39
  40 When no longer needed, the initialised B<EVP_AEAD_CTX> structure must be passed
  41 to EVP_AEAD_CTX_cleanup(), which will deallocate any memory used.
  42
  43 With an B<EVP_AEAD_CTX> in hand, one can seal and open messages. These
  44 operations are intended to meet the standard notions of privacy and
  45 authenticity for authenticated encryption. For formal definitions see I<Bellare
  46 and Namprempre>, "Authenticated encryption: relations among notions and
  47 analysis of the generic composition paradigm," Lecture Notes in Computer
  48 Science B<1976> (2000), 531–545,
  49 L<http://www-cse.ucsd.edu/~mihir/papers/oem.html>.
  50
  51 When sealing messages, a nonce must be given. The length of the nonce is fixed
  52 by the AEAD in use and is returned by EVP_AEAD_nonce_length(). I<The nonce must
  53 be unique for all messages with the same key>. This is critically important -
  54 nonce reuse may completely undermine the security of the AEAD. Nonces may be
  55 predictable and public, so long as they are unique. Uniqueness may be achieved
  56 with a simple counter or, if long enough, may be generated randomly. The nonce
  57 must be passed into the "open" operation by the receiver so must either be
  58 implicit (e.g. a counter), or must be transmitted along with the sealed message.
  59
  60 The "seal" and "open" operations are atomic - an entire message must be
  61 encrypted or decrypted in a single call. Large messages may have to be split up
  62 in order to accomodate this. When doing so, be mindful of the need not to
  63 repeat nonces and the possibility that an attacker could duplicate, reorder or
  64 drop message chunks. For example, using a single key for a given (large)
  65 message and sealing chunks with nonces counting from zero would be secure as
  66 long as the number of chunks was securely transmitted. (Otherwise an attacker
  67 could truncate the message by dropping chunks from the end.)
  68
  69 The number of chunks could be transmitted by prefixing it to the plaintext, for
  70 example. This also assumes that no other message would ever use the same key
  71 otherwise the rule that nonces must be unique for a given key would be
  72 violated.
  73
  74 The "seal" and "open" operations also permit additional data to be
  75 authenticated via the B<ad> parameter. This data is not included in the
  76 ciphertext and must be identical for both the "seal" and "open" call. This
  77 permits implicit context to be authenticated but may be C<NULL> if not needed.
  78
  79 The "seal" and "open" operations may work inplace if the B<out> and B<in>
  80 arguments are equal. They may also be used to shift the data left inside the
  81 same buffer if B<out> is less than B<in>. However, B<out> may not point inside
  82 the input data otherwise the input may be overwritten before it has been read.
  83 This case will cause an error.
  84
  85 =head1 RETURN VALUES
  86
  87 The "seal" and "open" operations return an C<ssize_t> with value -1 on error,
  88 otherwise they return the number of output bytes written. An error will be
  89 returned if the input length is large enough that the output size exceeds the
  90 range of a C<ssize_t>.
  91
  92 =head1 HISTORY
  93
  94 These functions were first added to OpenSSL 1.0.2.
  95
  96 =cut