symm/eax.h, symm/eax-def.h: Implement the EAX authenticated encryption mode.
[catacomb] / symm / eax-def.h
diff --git a/symm/eax-def.h b/symm/eax-def.h
new file mode 100644 (file)
index 0000000..6e1c7ca
--- /dev/null
@@ -0,0 +1,850 @@
+/* -*-c-*-
+ *
+ * The EAX authenticated-encryption mode
+ *
+ * (c) 2017 Straylight/Edgeware
+ */
+
+/*----- Licensing notice --------------------------------------------------*
+ *
+ * This file is part of Catacomb.
+ *
+ * Catacomb is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * Catacomb is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with Catacomb; if not, write to the Free
+ * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ * MA 02111-1307, USA.
+ */
+
+#ifndef CATACOMB_EAX_DEF_H
+#define CATACOMB_EAX_DEF_H
+
+#ifdef __cplusplus
+  extern "C" {
+#endif
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <string.h>
+
+#include <mLib/bits.h>
+#include <mLib/sub.h>
+
+#ifndef CATACOMB_ARENA_H
+#  include "arena.h"
+#endif
+
+#ifndef CATACOMB_BLKC_H
+#  include "blkc.h"
+#endif
+
+#ifndef CATACOMB_CT_H
+#  include "ct.h"
+#endif
+
+#ifndef CATACOMB_CMAC_H
+#  include "cmac.h"
+#endif
+
+#ifndef CATACOMB_CMAC_DEF_H
+#  include "cmac-def.h"
+#endif
+
+#ifndef CATACOMB_KEYSZ_H
+#  include "keysz.h"
+#endif
+
+#ifndef CATACOMB_PARANOIA_H
+#  include "paranoia.h"
+#endif
+
+#ifndef CATACOMB_RSVR_H
+#  include "rsvr.h"
+#endif
+
+/*----- Macros ------------------------------------------------------------*/
+
+/* --- @EAX_DEF@ --- *
+ *
+ * Arguments:  @PRE@, @pre@ = prefixes for the underlying block cipher
+ *
+ * Use:                Creates an implementation for the EAX authenticated-
+ *             encryption mode.
+ */
+
+#define EAX_DEF(PRE, pre) EAX_DEFX(PRE, pre, #pre, #pre)
+
+#define EAX_DEFX(PRE, pre, name, fname)                                        \
+                                                                       \
+OMAC_DECL(PRE, pre)                                                    \
+                                                                       \
+const octet                                                            \
+  pre##_eaxnoncesz[] = { KSZ_ANY, PRE##_BLKSZ },                       \
+  pre##_eaxtagsz[] = { KSZ_RANGE, PRE##_BLKSZ, 0, PRE##_BLKSZ, 1 };    \
+                                                                       \
+/* --- @pre_eaxsetkey@ --- *                                           \
+ *                                                                     \
+ * Arguments:  @pre_eaxkey *key@ = pointer to key block to fill in     \
+ *             @const void *k@ = pointer to key material               \
+ *             @size_t ksz@ = size of key material                     \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Initializes an EAX key block.                           \
+ */                                                                    \
+                                                                       \
+void pre##_eaxsetkey(pre##_eaxkey *key, const void *k, size_t ksz)     \
+{                                                                      \
+  uint32 t[PRE##_BLKSZ/4];                                             \
+                                                                       \
+  /* Initialize the block cipher. */                                   \
+  pre##_init(&key->ctx, k, ksz);                                       \
+                                                                       \
+  /* Set up the OMAC masks. */                                         \
+  pre##_omacmasks(&key->ctx, key->m0, key->m1);                                \
+                                                                       \
+  /* Set up the OMAC tweaks.  EAX tweaks its MAC by simply stitching   \
+   * magic block-wide prefixes %$t_0$%, %$t_1$%, %$t_2$% (which are    \
+   * simply the numbers 0, 1, 2) on the front of strings.  We can      \
+   * accelerate things by caching two values for each tweak:           \
+   *                                                                   \
+   *   * %$v_i = E_K(t_i)$% is the accumulator that results from       \
+   *    pushing the tweak through the blockcipher, which we'd          \
+   *    calculate if the original message was nonempty.                \
+   *                                                                   \
+   *   * %$z_i = E_K(t_0 \xor m_0)$% is the tweak with the `full final \
+   *    buffer' mask applied, which is the final tag for a final empty \
+   *    message. \
+   */                                                                  \
+  BLKC_BSET(PRE, t, 0); pre##_eblk(&key->ctx, t, key->v0);             \
+  BLKC_XMOVE(PRE, t, key->m0); pre##_eblk(&key->ctx, t, key->z0);      \
+  BLKC_BSET(PRE, t, 1); pre##_eblk(&key->ctx, t, key->v1);             \
+  BLKC_XMOVE(PRE, t, key->m0); pre##_eblk(&key->ctx, t, key->z1);      \
+  BLKC_BSET(PRE, t, 2); pre##_eblk(&key->ctx, t, key->v2);             \
+  BLKC_XMOVE(PRE, t, key->m0); pre##_eblk(&key->ctx, t, key->z2);      \
+}                                                                      \
+                                                                       \
+/* --- @pre_eaxaadinit@ --- *                                          \
+ *                                                                     \
+ * Arguments:  @pre_eaxaadctx *aad@ = pointer to AAD context           \
+ *             @const pre_eaxkey *key@ = pointer to key block          \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Initializes an EAX AAD (`additional authenticated       \
+ *             data') context associated with a given key.  AAD        \
+ *             contexts can be copied and/or reused, saving time if    \
+ *             the AAD for a number of messages has a common prefix.   \
+ *                                                                     \
+ *             The @key@ doesn't need to be kept around, though        \
+ *             usually there'll at least be another copy in some EAX   \
+ *             operation context because the AAD on its own isn't much \
+ *             good.                                                   \
+ */                                                                    \
+                                                                       \
+void pre##_eaxaadinit(pre##_eaxaadctx *aad, const pre##_eaxkey *key)   \
+  { aad->k = *key; aad->off = 0; BLKC_MOVE(PRE, aad->a, key->v1); }    \
+                                                                       \
+/* --- @pre_eaxaadhash@ --- *                                          \
+ *                                                                     \
+ * Arguments:  @pre_eaxaadctx *aad@ = pointer to AAD context           \
+ *             @const void *p@ = pointer to AAD material               \
+ *             @size_t sz@ = length of AAD material                    \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Feeds AAD into the context.                             \
+ */                                                                    \
+                                                                       \
+void pre##_eaxaadhash(pre##_eaxaadctx *aad, const void *p, size_t sz)  \
+{                                                                      \
+  rsvr_state st;                                                       \
+  const octet *q;                                                      \
+                                                                       \
+  rsvr_setup(&st, &pre##_omacpolicy, aad->b, &aad->off, p, sz);                \
+  RSVR_DO(&st) while ((q = RSVR_NEXT(&st, PRE##_BLKSZ)) != 0)          \
+    OMAC_BLOCK(PRE, pre, &aad->k.ctx, aad->a, q);                      \
+}                                                                      \
+                                                                       \
+/* --- @pre_eaxinit@ --- *                                             \
+ *                                                                     \
+ * Arguments:  @pre_eaxctx *ctx@ = pointer to EAX context              \
+ *             @const pre_eaxkey *key@ = pointer to key block          \
+ *             @const void *n@ = pointer to nonce                      \
+ *             @size_t nsz@ = size of nonce                            \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Initialize an EAX operation context with a given key.   \
+ *                                                                     \
+ *             The original key needn't be kept around any more.       \
+ */                                                                    \
+                                                                       \
+void pre##_eaxinit(pre##_eaxctx *ctx, const pre##_eaxkey *k,           \
+                  const void *n, size_t nsz)                           \
+  { ctx->k = *k; pre##_eaxreinit(ctx, n, nsz); }                       \
+                                                                       \
+/* --- @pre_eaxreinit@ --- *                                           \
+ *                                                                     \
+ * Arguments:  @pre_eaxctx *ctx@ = pointer to EAX context              \
+ *             @const void *n@ = pointer to nonce                      \
+ *             @size_t nsz@ = size of nonce                            \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Reinitialize an EAX operation context, changing the     \
+ *             nonce.                                                  \
+ */                                                                    \
+                                                                       \
+void pre##_eaxreinit(pre##_eaxctx *ctx, const void *n, size_t nsz)     \
+{                                                                      \
+  octet b[PRE##_BLKSZ];                                                        \
+  const octet *q = n;                                                  \
+                                                                       \
+  /* Initialize the OMAC context with the right tweak. */              \
+  BLKC_MOVE(PRE, ctx->a, ctx->k.v2);                                   \
+  ctx->off = 0;                                                                \
+                                                                       \
+  /* Calculate the initial counter from the nonce.  This is OMAC again,        \
+   * but this time we know that we're starting from a clean slate and  \
+   * we have the whole input in one go, so we don't bother with the    \
+   * full reservoir machinery.                                         \
+   */                                                                  \
+  if (!nsz)                                                            \
+    BLKC_MOVE(PRE, ctx->c0, ctx->k.z0);                                        \
+  else {                                                               \
+    BLKC_MOVE(PRE, ctx->c0, ctx->k.v0);                                        \
+    while (nsz > PRE##_BLKSZ) {                                                \
+      OMAC_BLOCK(PRE, pre, &ctx->k.ctx, ctx->c0, q);                   \
+      q += PRE##_BLKSZ; nsz -= PRE##_BLKSZ;                            \
+    }                                                                  \
+    memcpy(b, q, nsz);                                                 \
+    pre##_omacdone(&ctx->k.ctx, ctx->k.m0, ctx->k.m1,                  \
+                  ctx->c0, b, nsz);                                    \
+  }                                                                    \
+                                                                       \
+  /* We must remember the initial counter for the final tag            \
+   * calculation.  (I conjecture that storing the final counter instead        \
+   * would be just as secure, and require less state, but I've not     \
+   * proven this, and anyway it wouldn't interoperate.)  Copy it to    \
+   * make the working counter.                                         \
+   */                                                                  \
+  BLKC_MOVE(PRE, ctx->c, ctx->c0);                                     \
+}                                                                      \
+                                                                       \
+/* --- @pre_eaxencrypt@ --- *                                          \
+ *                                                                     \
+ * Arguments:  @pre_eaxctx *ctx@ = pointer to EAX operation context    \
+ *             @const void *src@ = pointer to plaintext message chunk  \
+ *             @size_t sz@ = size of the plaintext                     \
+ *             @buf *dst@ = a buffer to write the ciphertext to        \
+ *                                                                     \
+ * Returns:    Zero on success; @-1@ on failure.                       \
+ *                                                                     \
+ * Use:                Encrypts a chunk of a plaintext message, writing a      \
+ *             chunk of ciphertext to the output buffer and updating   \
+ *             the operation state.                                    \
+ *                                                                     \
+ *             For EAX, we always write a ciphertext chunk the same    \
+ *             size as the plaintext.  The messing about with @buf@    \
+ *             objects makes the interface consistent with other AEAD  \
+ *             schemes which can't do this.                            \
+ */                                                                    \
+                                                                       \
+int pre##_eaxencrypt(pre##_eaxctx *ctx,                                        \
+                    const void *src, size_t sz, buf *dst)              \
+{                                                                      \
+  rsvr_plan plan;                                                      \
+  uint32 t[PRE##_BLKSZ/4];                                             \
+  const octet *p = src;                                                        \
+  octet *q, *r, y;                                                     \
+                                                                       \
+  /* Allocate space for the ciphertext. */                             \
+  if (sz) { q = buf_get(dst, sz); if (!q) return (-1); }               \
+  else q = 0;                                                          \
+                                                                       \
+  /* Determine the buffering plan.  Our buffer is going to do double-  \
+   * duty here.  The end portion is going to contain mask from the     \
+   * encrypted counter which we mix into the plaintext to encrypt it;  \
+   * the start portion, which originally mask bytes we've already used,        \
+   * will hold the output ciphertext, which will eventually be         \
+   * collected into the OMAC state.                                    \
+   */                                                                  \
+  rsvr_mkplan(&plan, &pre##_omacpolicy, ctx->off, sz);                 \
+                                                                       \
+  /* Initial portion, fulfilled from the buffer.  If the buffer is     \
+   * empty, then that means that we haven't yet encrypted the current  \
+   * counter, so we should do that and advance it.                     \
+   */                                                                  \
+  if (plan.head) {                                                     \
+    if (!ctx->off) {                                                   \
+      pre##_eblk(&ctx->k.ctx, ctx->c, t); BLKC_BSTEP(PRE, ctx->c);     \
+      BLKC_STORE(PRE, ctx->b, t);                                      \
+    }                                                                  \
+    r = ctx->b + ctx->off; ctx->off += plan.head;                      \
+    while (plan.head--) { y = *p++ ^ *r; *r++ = *q++ = y; }            \
+  }                                                                    \
+                                                                       \
+  /* If we've filled up the buffer then we need to cycle the MAC and   \
+   * reset the offset.                                                 \
+   */                                                                  \
+  if (plan.from_rsvr) {                                                        \
+    OMAC_BLOCK(PRE, pre, &ctx->k.ctx, ctx->a, ctx->b);                 \
+    ctx->off = 0;                                                      \
+  }                                                                    \
+                                                                       \
+  /* Now to process the main body of the input.  We sneakily open-code \
+   * the OMAC part of this.                                            \
+   */                                                                  \
+  while (plan.from_input) {                                            \
+    pre##_eblk(&ctx->k.ctx, ctx->c, t); BLKC_BSTEP(PRE, ctx->c);       \
+    BLKC_XLOAD(PRE, t, p); p += PRE##_BLKSZ;                           \
+    BLKC_STORE(PRE, q, t); q += PRE##_BLKSZ;                           \
+    BLKC_XMOVE(PRE, ctx->a, t); pre##_eblk(&ctx->k.ctx, ctx->a, ctx->a); \
+    plan.from_input -= PRE##_BLKSZ;                                    \
+  }                                                                    \
+                                                                       \
+  /* Finally, deal with any final portion.  If there is one, we know   \
+   * that the buffer is empty: we must have filled it above, or this   \
+   * would all count as `initial' data.                                        \
+   */                                                                  \
+  if (plan.tail) {                                                     \
+    pre##_eblk(&ctx->k.ctx, ctx->c, t); BLKC_BSTEP(PRE, ctx->c);       \
+    BLKC_STORE(PRE, ctx->b, t);                                                \
+    r = ctx->b; ctx->off += plan.tail;                                 \
+    while (plan.tail--) { y = *p++ ^ *r; *r++ = *q++ = y; }            \
+  }                                                                    \
+                                                                       \
+  /* And we're done. */                                                        \
+  return (0);                                                          \
+}                                                                      \
+                                                                       \
+/* --- @pre_eaxdecrypt@ --- *                                          \
+ *                                                                     \
+ * Arguments:  @pre_eaxctx *ctx@ = pointer to EAX operation context    \
+ *             @const void *src@ = pointer to ciphertext message chunk \
+ *             @size_t sz@ = size of the ciphertext                    \
+ *             @buf *dst@ = a buffer to write the plaintext to         \
+ *                                                                     \
+ * Returns:    Zero on success; @-1@ on failure.                       \
+ *                                                                     \
+ * Use:                Decrypts a chunk of a ciphertext message, writing a     \
+ *             chunk of plaintext to the output buffer and updating    \
+ *             the operation state.                                    \
+ *                                                                     \
+ *             For EAX, we always write a plaintext chunk the same     \
+ *             size as the ciphertext.  The messing about with @buf@   \
+ *             objects makes the interface consistent with other AEAD  \
+ *             schemes which can't do this.                            \
+ */                                                                    \
+                                                                       \
+int pre##_eaxdecrypt(pre##_eaxctx *ctx,                                        \
+                    const void *src, size_t sz, buf *dst)              \
+{                                                                      \
+  rsvr_plan plan;                                                      \
+  uint32 t[PRE##_BLKSZ/4], u[PRE##_BLKSZ];                             \
+  const octet *p = src;                                                        \
+  octet *q, *r, y;                                                     \
+                                                                       \
+  /* Allocate space for the plaintext. */                              \
+  if (sz) { q = buf_get(dst, sz); if (!q) return (-1); }               \
+  else q = 0;                                                          \
+                                                                       \
+  /* Determine the buffering plan.  Our buffer is going to do double-  \
+   * duty here.  The end portion is going to contain mask from the     \
+   * encrypted counter which we mix into the plaintext to encrypt it;  \
+   * the start portion, which originally mask bytes we've already used,        \
+   * will hold the input ciphertext, which will eventually be          \
+   * collected into the OMAC state.                                    \
+   */                                                                  \
+  rsvr_mkplan(&plan, &pre##_omacpolicy, ctx->off, sz);                 \
+                                                                       \
+  /* Initial portion, fulfilled from the buffer.  If the buffer is     \
+   * empty, then that means that we haven't yet encrypted the current  \
+   * counter, so we should do that and advance it.                     \
+   */                                                                  \
+  if (plan.head) {                                                     \
+    if (!ctx->off) {                                                   \
+      pre##_eblk(&ctx->k.ctx, ctx->c, t); BLKC_BSTEP(PRE, ctx->c);     \
+      BLKC_STORE(PRE, ctx->b, t);                                      \
+    }                                                                  \
+    r = ctx->b + ctx->off; ctx->off += plan.head;                      \
+    while (plan.head--) { y = *p++; *q++ = y ^ *r; *r++ = y; }         \
+  }                                                                    \
+                                                                       \
+  /* If we've filled up the buffer then we need to cycle the MAC and   \
+   * reset the offset.                                                 \
+   */                                                                  \
+  if (plan.from_rsvr) {                                                        \
+    OMAC_BLOCK(PRE, pre, &ctx->k.ctx, ctx->a, ctx->b);                 \
+    ctx->off = 0;                                                      \
+  }                                                                    \
+                                                                       \
+  /* Now to process the main body of the input.  We sneakily open-code \
+   * the OMAC part of this.                                            \
+   */                                                                  \
+  while (plan.from_input) {                                            \
+    pre##_eblk(&ctx->k.ctx, ctx->c, t); BLKC_BSTEP(PRE, ctx->c);       \
+    BLKC_LOAD(PRE, u, p); p += PRE##_BLKSZ;                            \
+    BLKC_XSTORE(PRE, q, t, u); q += PRE##_BLKSZ;                       \
+    BLKC_XMOVE(PRE, ctx->a, u); pre##_eblk(&ctx->k.ctx, ctx->a, ctx->a); \
+    plan.from_input -= PRE##_BLKSZ;                                    \
+  }                                                                    \
+                                                                       \
+  /* Finally, deal with any final portion.  If there is one, we know   \
+   * that the buffer is empty: we must have filled it above, or this   \
+   * would all count as `initial' data.                                        \
+   */                                                                  \
+  if (plan.tail) {                                                     \
+    pre##_eblk(&ctx->k.ctx, ctx->c, t); BLKC_BSTEP(PRE, ctx->c);       \
+    BLKC_STORE(PRE, ctx->b, t);                                                \
+    r = ctx->b; ctx->off += plan.tail;                                 \
+    while (plan.tail--) { y = *p++; *q++ = y ^ *r; *r++ = y; }         \
+  }                                                                    \
+                                                                       \
+  /* And we're done. */                                                        \
+  return (0);                                                          \
+}                                                                      \
+                                                                       \
+/* --- @pre_eaxtag@ --- *                                              \
+ *                                                                     \
+ * Arguments:  @pre_eaxctx *ctx@ = pointer to an EAX context           \
+ *             @const pre_eaxaadctx *aad@ = pointer to AAD context, or \
+ *                     null                                            \
+ *             @octet *t@ = where to write a (full-length) tag         \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Finishes an EAX operation, by calculating the tag.      \
+ */                                                                    \
+                                                                       \
+static void pre##_eaxtag(pre##_eaxctx *ctx,                            \
+                        const pre##_eaxaadctx *aad, octet *t)          \
+{                                                                      \
+  octet b[PRE##_BLKSZ];                                                        \
+  uint32 u[PRE##_BLKSZ/4];                                             \
+                                                                       \
+  /* Finish tagging the ciphertext.  (The buffer is empty if and only  \
+   * if there was no message, since the OMAC reservoir policy leaves   \
+   * the buffer full.)                                                 \
+   */                                                                  \
+  if (!ctx->off) BLKC_MOVE(PRE, ctx->a, ctx->k.z2);                    \
+  else pre##_omacdone(&ctx->k.ctx, ctx->k.m0, ctx->k.m1,               \
+                     ctx->a, ctx->b, ctx->off);                        \
+                                                                       \
+  /* If there's no AAD, because the pointer is null or no data was     \
+   * supplied, then use the cached empty-header tag.  Otherwise                \
+   * calculate the tag for the AAD.  Either way, mix the result into   \
+   * ctx->A, and be careful not to modify the AAD context.  (Again, the        \
+   * buffer is empty if and only if there was no AAD.)                 \
+   */                                                                  \
+  if (!aad || !aad->off) BLKC_XMOVE(PRE, ctx->a, ctx->k.z1);           \
+  else {                                                               \
+    BLKC_MOVE(PRE, u, aad->a); memcpy(b, aad->b, aad->off);            \
+    pre##_omacdone(&ctx->k.ctx, ctx->k.m0, ctx->k.m1, u, b, aad->off); \
+    BLKC_XMOVE(PRE, ctx->a, u);                                                \
+  }                                                                    \
+                                                                       \
+  /* Finally, mix in the initial counter value. */                     \
+  BLKC_XMOVE(PRE, ctx->a, ctx->c0);                                    \
+                                                                       \
+  /* We're done. */                                                    \
+  BLKC_STORE(PRE, t, ctx->a);                                          \
+}                                                                      \
+                                                                       \
+/* --- @pre_eaxencryptdone@ --- *                                      \
+ *                                                                     \
+ * Arguments:  @pre_eaxctx *ctx@ = pointer to an EAX context           \
+ *             @const pre_eaxaadctx *aad@ = pointer to AAD context, or \
+ *                     null                                            \
+ *             @buf *dst@ = buffer for remaining ciphertext            \
+ *             @void *tag@ = where to write the tag                    \
+ *             @size_t tsz@ = length of tag to store                   \
+ *                                                                     \
+ * Returns:    Zero on success; @-1@ on failure.                       \
+ *                                                                     \
+ * Use:                Completes an EAX encryption operation.  The @aad@       \
+ *             pointer may be null if there is no additional           \
+ *             authenticated data.  EAX doesn't buffer ciphertext, but \
+ *             the output buffer is provided anyway for consistency    \
+ *             with other AEAD schemes which don't have this property; \
+ *             the function will fail if the output buffer is broken.  \
+ */                                                                    \
+                                                                       \
+int pre##_eaxencryptdone(pre##_eaxctx *ctx,                            \
+                        const pre##_eaxaadctx *aad, buf *dst,          \
+                        void *tag, size_t tsz)                         \
+{                                                                      \
+  octet t[PRE##_BLKSZ];                                                        \
+                                                                       \
+  if (tsz > PRE##_BLKSZ) return (-1);                                  \
+  if (!BOK(dst)) return (-1);                                          \
+  pre##_eaxtag(ctx, aad, t); memcpy(tag, t, tsz);                      \
+  return (0);                                                          \
+}                                                                      \
+                                                                       \
+/* --- @pre_eaxdecryptdone@ --- *                                      \
+ *                                                                     \
+ * Arguments:  @pre_eaxctx *ctx@ = pointer to an EAX context           \
+ *             @const pre_eaxaadctx *aad@ = pointer to AAD context, or \
+ *                     null                                            \
+ *             @buf *dst@ = buffer for remaining plaintext             \
+ *             @const void *tag@ = tag to verify                       \
+ *             @size_t tsz@ = length of tag                            \
+ *                                                                     \
+ * Returns:    @+1@ for complete success; @0@ if tag verification      \
+ *             failed; @-1@ for other kinds of errors.                 \
+ *                                                                     \
+ * Use:                Completes an EAX decryption operation.  The @aad@       \
+ *             pointer may be null if there is no additional           \
+ *             authenticated data.  EAX doesn't buffer plaintext, but  \
+ *             the output buffer is provided anyway for consistency    \
+ *             with other AEAD schemes which don't have this property; \
+ *             the function will fail if the output buffer is broken.  \
+ */                                                                    \
+                                                                       \
+int pre##_eaxdecryptdone(pre##_eaxctx *ctx,                            \
+                        const pre##_eaxaadctx *aad, buf *dst,          \
+                        const void *tag, size_t tsz)                   \
+{                                                                      \
+  octet t[PRE##_BLKSZ];                                                        \
+                                                                       \
+  if (tsz > PRE##_BLKSZ) return (-1);                                  \
+  if (!BOK(dst)) return (-1);                                          \
+  pre##_eaxtag(ctx, aad, t);                                           \
+  if (!ct_memeq(tag, t, tsz)) return (0);                              \
+  else return (+1);                                                    \
+}                                                                      \
+                                                                       \
+/* --- Generic AEAD interface --- */                                   \
+                                                                       \
+typedef struct gactx {                                                 \
+  gaead_aad a;                                                         \
+  pre##_eaxaadctx aad;                                                 \
+} gactx;                                                               \
+                                                                       \
+                                                                       \
+static gaead_aad *gadup(const gaead_aad *a)                            \
+  { gactx *aad = S_CREATE(gactx); *aad = *(gactx *)a; return (&aad->a); } \
+                                                                       \
+static void gahash(gaead_aad *a, const void *h, size_t hsz)            \
+  { gactx *aad = (gactx *)a; pre##_eaxaadhash(&aad->aad, h, hsz); }    \
+                                                                       \
+static void gadestroy(gaead_aad *a)                                    \
+  { gactx *aad = (gactx *)a; BURN(*aad); S_DESTROY(aad); }             \
+                                                                       \
+static const gaead_aadops gaops =                                      \
+  { &pre##_eax, gadup, gahash, gadestroy };                            \
+                                                                       \
+static gaead_aad *gaad(const pre##_eaxkey *k)                          \
+{                                                                      \
+  gactx *aad = S_CREATE(gactx);                                                \
+  aad->a.ops = &gaops;                                                 \
+  pre##_eaxaadinit(&aad->aad, k);                                      \
+  return (&aad->a);                                                    \
+}                                                                      \
+                                                                       \
+typedef struct gectx {                                                 \
+  gaead_enc e;                                                         \
+  pre##_eaxctx ctx;                                                    \
+} gectx;                                                               \
+                                                                       \
+static gaead_aad *geaad(gaead_enc *e)                                  \
+  { gectx *enc = (gectx *)e; return (gaad(&enc->ctx.k)); }             \
+                                                                       \
+static int gereinit(gaead_enc *e, const void *n, size_t nsz,           \
+                   size_t hsz, size_t msz, size_t tsz)                 \
+{                                                                      \
+  gectx *enc = (gectx *)e;                                             \
+                                                                       \
+  if (tsz > PRE##_BLKSZ) return (-1);                                  \
+  pre##_eaxreinit(&enc->ctx, n, nsz);                                  \
+  return (0);                                                          \
+}                                                                      \
+                                                                       \
+static int geenc(gaead_enc *e, const void *m, size_t msz, buf *b)      \
+{                                                                      \
+  gectx *enc = (gectx *)e;                                             \
+  return (pre##_eaxencrypt(&enc->ctx, m, msz, b));                     \
+}                                                                      \
+                                                                       \
+static int gedone(gaead_enc *e, const gaead_aad *a,                    \
+                 buf *b, void *t, size_t tsz)                          \
+{                                                                      \
+  gectx *enc = (gectx *)e; gactx *aad = (gactx *)a;                    \
+  assert(!a || a->ops == &gaops);                                      \
+  return (pre##_eaxencryptdone(&enc->ctx, a ? &aad->aad : 0, b, t, tsz)); \
+}                                                                      \
+                                                                       \
+static void gedestroy(gaead_enc *e)                                    \
+  { gectx *enc = (gectx *)e; BURN(*enc); S_DESTROY(enc); }             \
+                                                                       \
+static const gaead_encops geops =                                      \
+  { &pre##_eax, geaad, gereinit, geenc, gedone, gedestroy };           \
+                                                                       \
+typedef struct gdctx {                                                 \
+  gaead_dec d;                                                         \
+  pre##_eaxctx ctx;                                                    \
+} gdctx;                                                               \
+                                                                       \
+static gaead_aad *gdaad(gaead_dec *d)                                  \
+  { gdctx *dec = (gdctx *)d; return (gaad(&dec->ctx.k)); }             \
+                                                                       \
+static int gdreinit(gaead_dec *d, const void *n, size_t nsz,           \
+                   size_t hsz, size_t csz, size_t tsz)                 \
+{                                                                      \
+  gdctx *dec = (gdctx *)d;                                             \
+                                                                       \
+  if (tsz > PRE##_BLKSZ) return (-1);                                  \
+  pre##_eaxreinit(&dec->ctx, n, nsz);                                  \
+  return (0);                                                          \
+}                                                                      \
+                                                                       \
+static int gddec(gaead_dec *d, const void *c, size_t csz, buf *b)      \
+{                                                                      \
+  gdctx *dec = (gdctx *)d;                                             \
+  return (pre##_eaxdecrypt(&dec->ctx, c, csz, b));                     \
+}                                                                      \
+                                                                       \
+static int gddone(gaead_dec *d, const gaead_aad *a,                    \
+                 buf *b, const void *t, size_t tsz)                    \
+{                                                                      \
+  gdctx *dec = (gdctx *)d; gactx *aad = (gactx *)a;                    \
+  assert(!a || a->ops == &gaops);                                      \
+  return (pre##_eaxdecryptdone(&dec->ctx, a ? &aad->aad : 0, b, t, tsz)); \
+}                                                                      \
+                                                                       \
+static void gddestroy(gaead_dec *d)                                    \
+  { gdctx *dec = (gdctx *)d; BURN(*dec); S_DESTROY(dec); }             \
+                                                                       \
+static const gaead_decops gdops =                                      \
+  { &pre##_eax, gdaad, gdreinit, gddec, gddone, gddestroy };           \
+                                                                       \
+typedef struct gkctx {                                                 \
+  gaead_key k;                                                         \
+  pre##_eaxkey key;                                                    \
+} gkctx;                                                               \
+                                                                       \
+static gaead_aad *gkaad(const gaead_key *k)                            \
+  { gkctx *key = (gkctx *)k; return (gaad(&key->key)); }               \
+                                                                       \
+static gaead_enc *gkenc(const gaead_key *k, const void *n, size_t nsz, \
+                       size_t hsz, size_t msz, size_t tsz)             \
+{                                                                      \
+  gkctx *key = (gkctx *)k;                                             \
+  gectx *enc;                                                          \
+                                                                       \
+  if (tsz > PRE##_BLKSZ) return (0);                                   \
+  enc = S_CREATE(gectx); enc->e.ops = &geops;                          \
+  pre##_eaxinit(&enc->ctx, &key->key, n, nsz);                         \
+  return (&enc->e);                                                    \
+}                                                                      \
+                                                                       \
+static gaead_dec *gkdec(const gaead_key *k, const void *n, size_t nsz, \
+                       size_t hsz, size_t csz, size_t tsz)             \
+{                                                                      \
+  gkctx *key = (gkctx *)k;                                             \
+  gdctx *dec;                                                          \
+                                                                       \
+  if (tsz > PRE##_BLKSZ) return (0);                                   \
+  dec = S_CREATE(gdctx); dec->d.ops = &gdops;                          \
+  pre##_eaxinit(&dec->ctx, &key->key, n, nsz);                         \
+  return (&dec->d);                                                    \
+}                                                                      \
+                                                                       \
+static void gkdestroy(gaead_key *k)                                    \
+  { gkctx *key = (gkctx *)k; BURN(*key); S_DESTROY(key); }             \
+                                                                       \
+static const gaead_keyops gkops =                                      \
+  { &pre##_eax, gkaad, gkenc, gkdec, gkdestroy };                      \
+                                                                       \
+static gaead_key *gckey(const void *k, size_t ksz)                     \
+{                                                                      \
+  gkctx *key = S_CREATE(gkctx);                                                \
+  key->k.ops = &gkops;                                                 \
+  pre##_eaxsetkey(&key->key, k, ksz);                                  \
+  return (&key->k);                                                    \
+}                                                                      \
+                                                                       \
+const gcaead pre##_eax = {                                             \
+  name "-eax",                                                         \
+  pre##_keysz, pre##_eaxnoncesz, pre##_eaxtagsz,                       \
+  PRE##_BLKSZ, 0, 0, 0,                                                        \
+  gckey                                                                        \
+};                                                                     \
+                                                                       \
+EAX_TESTX(PRE, pre, name, fname)
+
+/*----- Test rig ----------------------------------------------------------*/
+
+#define EAX_TEST(PRE, pre) EAX_TESTX(PRE, pre, #pre, #pre)
+
+/* --- @EAX_TEST@ --- *
+ *
+ * Arguments:  @PRE, pre@ = prefixes for the underlying block cipher
+ *
+ * Use:                Standard test rig for EAX functions.
+ */
+
+#ifdef TEST_RIG
+
+#include <stdio.h>
+
+#include <mLib/dstr.h>
+#include <mLib/quis.h>
+#include <mLib/testrig.h>
+
+#define EAX_TESTX(PRE, pre, name, fname)                               \
+                                                                       \
+static int eaxverify(dstr *v)                                          \
+{                                                                      \
+  pre##_eaxkey key;                                                    \
+  pre##_eaxaadctx aad;                                                 \
+  pre##_eaxctx ctx;                                                    \
+  int ok = 1, win;                                                     \
+  int i;                                                               \
+  octet *p;                                                            \
+  int szs[] = { 1, 7, 192, -1, 0 }, *ip;                               \
+  size_t hsz, msz;                                                     \
+  dstr d = DSTR_INIT, t = DSTR_INIT;                                   \
+  buf b;                                                               \
+                                                                       \
+  dstr_ensure(&d, v[4].len > v[3].len ? v[4].len : v[3].len);          \
+  dstr_ensure(&t, v[5].len); t.len = v[5].len;                         \
+                                                                       \
+  pre##_eaxsetkey(&key, v[0].buf, v[0].len);                           \
+                                                                       \
+  for (ip = szs; *ip; ip++) {                                          \
+                                                                       \
+    pre##_eaxinit(&ctx, &key, (octet *)v[1].buf, v[1].len);            \
+                                                                       \
+    i = *ip;                                                           \
+    hsz = v[2].len;                                                    \
+    if (i == -1) i = hsz;                                              \
+    if (i > hsz) continue;                                             \
+    p = (octet *)v[2].buf;                                             \
+    pre##_eaxaadinit(&aad, &key);                                      \
+    while (hsz) {                                                      \
+      if (i > hsz) i = hsz;                                            \
+      pre##_eaxaadhash(&aad, p, i);                                    \
+      p += i; hsz -= i;                                                        \
+    }                                                                  \
+                                                                       \
+    buf_init(&b, d.buf, d.sz);                                         \
+    i = *ip;                                                           \
+    msz = v[3].len;                                                    \
+    if (i == -1) i = msz;                                              \
+    if (i > msz) continue;                                             \
+    p = (octet *)v[3].buf;                                             \
+    while (msz) {                                                      \
+      if (i > msz) i = msz;                                            \
+      if (pre##_eaxencrypt(&ctx, p, i, &b)) {                          \
+       puts("!! eaxencrypt reports failure");                          \
+       goto fail_enc;                                                  \
+      }                                                                        \
+      p += i; msz -= i;                                                        \
+    }                                                                  \
+                                                                       \
+    if (pre##_eaxencryptdone(&ctx, &aad, &b, (octet *)t.buf, t.len)) { \
+      puts("!! eaxencryptdone reports failure");                       \
+      goto fail_enc;                                                   \
+    }                                                                  \
+    d.len = BLEN(&b);                                                  \
+                                                                       \
+    if (d.len != v[4].len ||                                           \
+       memcmp(d.buf, v[4].buf, v[4].len) != 0 ||                       \
+       memcmp(t.buf, v[5].buf, v[5].len) != 0) {                       \
+    fail_enc:                                                          \
+      printf("\nfail encrypt:\n\tstep = %i", *ip);                     \
+      fputs("\n\tkey = ", stdout); type_hex.dump(&v[0], stdout);       \
+      fputs("\n\tnonce = ", stdout); type_hex.dump(&v[1], stdout);     \
+      fputs("\n\theader = ", stdout); type_hex.dump(&v[2], stdout);    \
+      fputs("\n\tmessage = ", stdout); type_hex.dump(&v[3], stdout);   \
+      fputs("\n\texp ct = ", stdout); type_hex.dump(&v[4], stdout);    \
+      fputs("\n\tcalc ct = ", stdout); type_hex.dump(&d, stdout);      \
+      fputs("\n\texp tag = ", stdout); type_hex.dump(&v[5], stdout);   \
+      fputs("\n\tcalc tag = ", stdout); type_hex.dump(&t, stdout);     \
+      putchar('\n');                                                   \
+      ok = 0;                                                          \
+    }                                                                  \
+                                                                       \
+    pre##_eaxinit(&ctx, &key, (octet *)v[1].buf, v[1].len);            \
+                                                                       \
+    buf_init(&b, d.buf, d.sz);                                         \
+    i = *ip;                                                           \
+    msz = v[4].len;                                                    \
+    if (i == -1) i = msz;                                              \
+    if (i > msz) continue;                                             \
+    p = (octet *)v[4].buf;                                             \
+    while (msz) {                                                      \
+      if (i > msz) i = msz;                                            \
+      if (pre##_eaxdecrypt(&ctx, p, i, &b)) {                          \
+       puts("!! eaxdecrypt reports failure");                          \
+       win = 0; goto fail_dec;                                         \
+      }                                                                        \
+      p += i; msz -= i;                                                        \
+    }                                                                  \
+                                                                       \
+    win = pre##_eaxdecryptdone(&ctx, &aad, &b,                         \
+                              (octet *)v[5].buf, v[5].len);            \
+    if (win < 0) {                                                     \
+      puts("!! eaxdecryptdone reports failure");                       \
+      goto fail_dec;                                                   \
+    }                                                                  \
+    d.len = BLEN(&b);                                                  \
+                                                                       \
+    if (d.len != v[3].len || !win ||                                   \
+       memcmp(d.buf, v[3].buf, v[3].len) != 0) {                       \
+    fail_dec:                                                          \
+      printf("\nfail decrypt:\n\tstep = %i", *ip);                     \
+      fputs("\n\tkey = ", stdout); type_hex.dump(&v[0], stdout);       \
+      fputs("\n\tnonce = ", stdout); type_hex.dump(&v[1], stdout);     \
+      fputs("\n\theader = ", stdout); type_hex.dump(&v[2], stdout);    \
+      fputs("\n\tciphertext = ", stdout); type_hex.dump(&v[4], stdout);        \
+      fputs("\n\texp pt = ", stdout); type_hex.dump(&v[3], stdout);    \
+      fputs("\n\tcalc pt = ", stdout); type_hex.dump(&d, stdout);      \
+      fputs("\n\ttag = ", stdout); type_hex.dump(&v[5], stdout);       \
+      printf("\n\tverify %s", win ? "ok" : "FAILED");                  \
+      putchar('\n');                                                   \
+      ok = 0;                                                          \
+    }                                                                  \
+  }                                                                    \
+                                                                       \
+  dstr_destroy(&d); dstr_destroy(&t);                                  \
+  return (ok);                                                         \
+}                                                                      \
+                                                                       \
+static test_chunk aeaddefs[] = {                                       \
+  { name "-eax", eaxverify,                                            \
+    { &type_hex, &type_hex, &type_hex, &type_hex,                      \
+      &type_hex, &type_hex, 0 } },                                     \
+  { 0, 0, { 0 } }                                                      \
+};                                                                     \
+                                                                       \
+int main(int argc, char *argv[])                                       \
+{                                                                      \
+  ego(argv[0]);                                                                \
+  test_run(argc, argv, aeaddefs, SRCDIR"/t/" fname);                   \
+  return (0);                                                          \
+}
+
+#else
+#  define EAX_TESTX(PRE, pre, name, fname)
+#endif
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+  }
+#endif
+
+#endif