diff --git a/ChangeLog b/ChangeLog index a97556e87e204522e37f14887d0c832de111a241..30771788464c4a0bfaa0f57a0f2f34f05aca16d1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -3,6 +3,7 @@ * nettle.texinfo (GCM): Document GCM_DIGEST_SIZE. (UMAC): Document new UMAC constants. (Keyed hash functions): Make HMAC and UMAC their own info nodes. + (EAX): Document EAX. * umac.h (UMAC_MIN_NONCE_SIZE, UMAC_MAX_NONCE_SIZE): New constants. diff --git a/nettle.texinfo b/nettle.texinfo index 3601cd5941fea6e811266c5680f77012af3fbbba..287b3a38a98453ba8302085d81d66ae17b5a427e 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -1827,6 +1827,7 @@ signature to authenticate the message. @menu * CBC:: * CTR:: +* EAX:: * GCM:: * CCM:: @end menu @@ -1925,7 +1926,7 @@ These macros use some tricks to make the compiler display a warning if the types of @var{f} and @var{ctx} don't match, e.g. if you try to use an @code{struct aes_ctx} context with the @code{des_encrypt} function. -@node CTR, GCM, CBC, Cipher modes +@node CTR, EAX, CBC, Cipher modes @comment node-name, next, previous, up @subsection Counter mode @@ -2001,7 +2002,190 @@ last three arguments define the source and destination area for the operation. @end deffn -@node GCM, CCM, CTR, Cipher modes +@node EAX, GCM, CTR, Cipher modes +@comment node-name, next, previous, up +@subsection EAX + +The @acronym{EAX} mode combines @acronym{CTR} mode encryption, +@xref{CTR}, with a message authentication based on @acronym{CBC}, +@xref{CBC}. It is defined on top of a block cipher, and only the +encryption function of this cipher is used. The implementation in Nettle +is restricted to ciphers with a block size of 128 bits (16 octets). +@acronym{EAX} was defined as a reaction to the @acronym{CCM} mode, +@xref{CCM}, which uses the same primitives but has some undesirable and +inelegant properties. + +The @acronym{EAX} mode provides both encryption and authentication. For +@acronym{EAX} encryption, the inputs are: + +@itemize +@item +The key, which can be used for many messages. +@item +A nonce, of arbitrary size, which must be unique for each message using +the same key. +@item +Additional associated data to be authenticated, but not included in the +message. +@item +The cleartext message to be encrypted. +@end itemize + +The outputs are: + +@itemize +@item +A ciphertext, of the same size as the cleartext. +@item +An authentication tag, or digest, of size up to one block of the +underlying cipher. +@end itemize + +Usually, the authentication tag should be appended at the end of the +ciphertext, producing an encrypted message which is slightly longer than +the cleartext. + +Nettle's support for @acronym{EAX} consists of a low-level general +interface, some convenience macros, and specific functions for +@acronym{EAX} using @acronym{AES}128 as the underlying cipher. These +interfaces are defined in @file{} + +@subsubsection General @acronym{EAX} interface + +@deftp {Context struct} {struct eax_key} +@acronym{EAX} state which depends only on the key, but not on the nonce +or the message. +@end deftp + +@deftp {Context struct} {struct eax_ctx} +Holds state corresponding to a particular message. +@end deftp + +@defvr Constant EAX_BLOCK_SIZE +@acronym{EAX}'s block size, 16. +@end defvr + +@defvr Constant EAX_DIGEST_SIZE +Size of the @acronym{EAX} digest, also 16. +@end defvr + +@deftypefun void eax_set_key (struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}) +Initializes @var{key}. @var{cipher} gives a context struct for the +underlying cipher, which must have been previously initialized for +encryption, and @var{f} is the encryption function. +@end deftypefun + +@deftypefun void eax_set_nonce (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{nonce_length}, const uint8_t *@var{nonce}) +Initializes @var{ctx} for processing a new message, using the given +nonce. +@end deftypefun + +@deftypefun void eax_update (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{data_length}, const uint8_t *@var{data}) +Process associated data for authentication. All but the last call for +each message @emph{must} use a length that is a multiple of the block +size. Unlike many other AEAD constructions, for @acronym{EAX} it's not +necessary to complete the processing of all associated data before +encrypting or decrypting the message data. +@end deftypefun + +@deftypefun void eax_encrypt (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) +@deftypefunx void eax_decrypt (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Encrypts or decrypts the data of a message. @var{cipher} is the context +struct for the underlying cipher and @var{f} is the encryption function. +All but the last call for each message @emph{must} use a length that is +a multiple of the block size. +@end deftypefun + +@deftypefun void eax_digest (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{digest}); +Extracts the message digest (also known ``authentication tag''). This is +the final operation when processing a message. If @var{length} is +smaller than @code{EAX_DIGEST_SIZE}, only the first @var{length} octets +of the digest are written. +@end deftypefun + + +@subsubsection @acronym{EAX} helper macros + +The following macros are defined. + +@deffn Macro EAX_CTX (@var{context_type}) +This defines an all-in-one context struct, including the context of the +underlying cipher and all @acronym{EAX} state. It expands +to +@example +@{ + struct eax_key key; + struct eax_ctx eax; + context_type cipher; +@} +@end example +@end deffn + +For all these macros, @var{ctx}, is a context struct as defined by +@code{EAX_CTX}, and @var{encrypt} is the encryption function of the +underlying cipher. + +@deffn Macro EAX_SET_KEY (@var{ctx}, @var{set_key}, @var{encrypt}, @var{key}) +@var{set_key} is the function for setting the encryption key for the +underlying cipher, and @var{key} is the key. +@end deffn + +@deffn Macro EAX_SET_NONCE (@var{ctx}, @var{encrypt}, @var{length}, @var{nonce}) +Sets the nonce to be used for the message. +@end deffn + +@deffn Macro EAX_UPDATE (@var{ctx}, @var{encrypt}, @var{length}, @var{data}) +Process associated data for authentication. +@end deffn + +@deffn Macro EAX_ENCRYPT (@var{ctx}, @var{encrypt}, @var{length}, @var{dst}, @var{src}) +@deffnx Macro EAX_DECRYPT (@var{ctx}, @var{encrypt}, @var{length}, @var{dst}, @var{src}) +Process message data for encryption or decryption. +@end deffn + +@deffn Macro EAX_DIGEST (@var{ctx}, @var{encrypt}, @var{length}, @var{digest}) +Extract te authentication tag for the message. +@end deffn + + +@subsubsection @acronym{EAX}-@acronym{AES}128 interface + +The following functions implement @acronym{EAX} using @acronym{AES}-128 +as the underlying cipher. + +@deftp {Context struct} {struct eax_aes128_ctx} +The context struct, defined using @code{EAX_CTX}. +@end deftp + +@deftypefun void eax_aes128_set_key (struct eax_aes128_ctx *@var{ctx}, const uint8_t *@var{key}) +Initializes @var{ctx} using the given key. +@end deftypefun + +@deftypefun void eax_aes128_set_nonce (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{iv}) +Initializes the per-message state, using the given nonce. +@end deftypefun + +@deftypefun void eax_aes128_update (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) +Process associated data for authentication. All but the last call for +each message @emph{must} use a length that is a multiple of the block +size. +@end deftypefun + +@deftypefun void eax_aes128_encrypt (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) +@deftypefunx void eax_aes128_decrypt (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Encrypts or decrypts the data of a message. All but the last call for +each message @emph{must} use a length that is a multiple of the block +size. +@end deftypefun + +@deftypefun void eax_aes128_digest (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}); +Extracts the message digest (also known ``authentication tag''). This is +the final operation when processing a message. If @var{length} is +smaller than @code{EAX_DIGEST_SIZE}, only the first @var{length} octets +of the digest are written. +@end deftypefun + +@node GCM, CCM, EAX, Cipher modes @comment node-name, next, previous, up @subsection Galois counter mode