Counter mode ciphers and pseudo-random generator.
authormdw <mdw>
Sat, 17 Jun 2000 10:51:42 +0000 (10:51 +0000)
committermdw <mdw>
Sat, 17 Jun 2000 10:51:42 +0000 (10:51 +0000)
counter-def.h [new file with mode: 0644]
counter.h [new file with mode: 0644]

diff --git a/counter-def.h b/counter-def.h
new file mode 100644 (file)
index 0000000..080321a
--- /dev/null
@@ -0,0 +1,543 @@
+/* -*-c-*-
+ *
+ * $Id: counter-def.h,v 1.1 2000/06/17 10:51:42 mdw Exp $
+ *
+ * Block cipher counter mode (or long cycle mode)
+ *
+ * (c) 2000 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.
+ */
+
+/*----- Revision history --------------------------------------------------* 
+ *
+ * $Log: counter-def.h,v $
+ * Revision 1.1  2000/06/17 10:51:42  mdw
+ * Counter mode ciphers and pseudo-random generator.
+ *
+ */
+
+#ifndef CATACOMB_COUNTER_DEF_H
+#define CATACOMB_COUNTER_DEF_H
+
+#ifdef __cplusplus
+  extern "C" {
+#endif
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <stdarg.h>
+#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_GCIPHER_H
+#  include "gcipher.h"
+#endif
+
+#ifndef CATACOMB_PARANOIA_H
+#  include "paranoia.h"
+#endif
+
+/*----- Macros ------------------------------------------------------------*/
+
+/* --- @COUNTER_DEF@ --- *
+ *
+ * Arguments:  @PRE@, @pre@ = prefixes for the underlying block cipher
+ *
+ * Use:                Creates definitions for counter mode.
+ */
+
+#define COUNTER_DEF(PRE, pre)                                          \
+                                                                       \
+/* --- @pre_countergetiv@ --- *                                                \
+ *                                                                     \
+ * Arguments:  @const pre_counterctx *ctx@ = pointer to counter        \
+ *                     context                                         \
+ *             @void *iv#@ = pointer to output data block              \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Reads the currently set IV.  Reading and setting an IV  \
+ *             is not transparent to the cipher.  It will add a `step' \
+ *             which must be matched by a similar operation during     \
+ *             decryption.                                             \
+ */                                                                    \
+                                                                       \
+void pre##_countergetiv(const pre##_counterctx *ctx, void *iv)         \
+{                                                                      \
+  BLKC_STORE(PRE, iv, ctx->n);                                         \
+}                                                                      \
+                                                                       \
+/* --- @pre_countersetiv@ --- *                                                \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to counter context      \
+ *             @cnost void *iv@ = pointer to IV to set                 \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Sets the IV to use for subsequent encryption.           \
+ */                                                                    \
+                                                                       \
+void pre##_countersetiv(pre##_counterctx *ctx, const void *iv)         \
+{                                                                      \
+  BLKC_LOAD(PRE, ctx->n, iv);                                          \
+  ctx->off = PRE##_BLKSZ;                                              \
+}                                                                      \
+                                                                       \
+/* --- @pre_counterbdry@ --- *                                         \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to counter context      \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Inserts a boundary during encryption.  Successful       \
+ *             decryption must place a similar boundary.               \
+ */                                                                    \
+                                                                       \
+void pre##_counterbdry(pre##_counterctx *ctx)                          \
+{                                                                      \
+  BLKC_STEP(PRE, ctx->n);                                              \
+  ctx->off = PRE##_BLKSZ;                                              \
+}                                                                      \
+                                                                       \
+/* --- @pre_countersetkey@ --- *                                       \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to counter context      \
+ *             @const pre_ctx *k@ = pointer to cipher context          \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Sets the counter context to use a different cipher key. \
+ */                                                                    \
+                                                                       \
+void pre##_countersetkey(pre##_counterctx *ctx, const pre##_ctx *k)    \
+{                                                                      \
+  ctx->ctx = *k;                                                       \
+}                                                                      \
+                                                                       \
+/* --- @pre_counterinit@ --- *                                         \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to cipher context       \
+ *             @const void *key@ = pointer to the key buffer           \
+ *             @size_t sz@ = size of the key                           \
+ *             @const void *iv@ = pointer to initialization vector     \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Initializes a counter context ready for use.  You       \
+ *             should ensure that the IV chosen is unique: reusing an  \
+ *             IV will compromise the security of the entire           \
+ *             plaintext.  This is equivalent to calls to @pre_init@,  \
+ *             @pre_countersetkey@ and @pre_countersetiv@.             \
+ */                                                                    \
+                                                                       \
+void pre##_counterinit(pre##_counterctx *ctx,                          \
+                      const void *key, size_t sz,                      \
+                      const void *iv)                                  \
+{                                                                      \
+  static octet zero[PRE##_BLKSZ] = { 0 };                              \
+  pre##_init(&ctx->ctx, key, sz);                                      \
+  pre##_countersetiv(ctx, iv ? iv : zero);                             \
+}                                                                      \
+                                                                       \
+/* --- @pre_counterencrypt@ --- *                                      \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to counter context      \
+ *             @const void *src@ = pointer to source data              \
+ *             @void *dest@ = pointer to destination data              \
+ *             @size_t sz@ = size of block to be encrypted             \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Encrypts or decrypts a block with a block cipher in     \
+ *             counter mode: encryption and decryption are the same in \
+ *             counter.  The destination may be null to just churn the \
+ *             feedback round for a bit.  The source may be null to    \
+ *             use the cipher as a random data generator.              \
+ */                                                                    \
+                                                                       \
+void pre##_counterencrypt(pre##_counterctx *ctx,                       \
+                         const void *src, void *dest,                  \
+                         size_t sz)                                    \
+{                                                                      \
+  const octet *s = src;                                                        \
+  octet *d = dest;                                                     \
+  unsigned off = ctx->off;                                             \
+                                                                       \
+  /* --- Empty blocks are trivial --- */                               \
+                                                                       \
+  if (!sz)                                                             \
+    return;                                                            \
+                                                                       \
+  /* --- If I can deal with the block from my buffer, do that --- */   \
+                                                                       \
+  if (sz < PRE##_BLKSZ - off)                                          \
+    goto small;                                                                \
+                                                                       \
+  /* --- Finish off what's left in my buffer --- */                    \
+                                                                       \
+  if (!d)                                                              \
+    sz -= PRE##_BLKSZ - off;                                           \
+  else {                                                               \
+    while (off < PRE##_BLKSZ) {                                                \
+      register octet x = s ? *s++ : 0;                                 \
+      *d++ = ctx->buf[off++] ^ x;                                      \
+      sz--;                                                            \
+    }                                                                  \
+  }                                                                    \
+                                                                       \
+  /* --- Main encryption loop --- */                                   \
+                                                                       \
+  {                                                                    \
+    uint32 n[PRE##_BLKSZ / 4];                                         \
+                                                                       \
+    for (;;) {                                                         \
+      pre##_eblk(&ctx->ctx, ctx->n, n);                                        \
+      BLKC_STEP(PRE, ctx->n);                                          \
+      if (sz < PRE##_BLKSZ)                                            \
+       break;                                                          \
+      if (d) {                                                         \
+       if (!s)                                                         \
+         BLKC_STORE(PRE, d, n);                                        \
+       else {                                                          \
+         uint32 x[PRE##_BLKSZ / 4];                                    \
+         BLKC_LOAD(PRE, x, s);                                         \
+         BLKC_XSTORE(PRE, d, n, x);                                    \
+         s += PRE##_BLKSZ;                                             \
+       }                                                               \
+       d += PRE##_BLKSZ;                                               \
+      }                                                                        \
+      sz -= PRE##_BLKSZ;                                               \
+    }                                                                  \
+                                                                       \
+    BLKC_STORE(PRE, ctx->buf, n);                                      \
+    off = 0;                                                           \
+  }                                                                    \
+                                                                       \
+  /* --- Tidying up the tail end --- */                                        \
+                                                                       \
+  if (sz) {                                                            \
+  small:                                                               \
+    if (!d)                                                            \
+      off += sz;                                                       \
+    else do {                                                          \
+      register octet x = s ? *s++ : 0;                                 \
+      *d++ = ctx->buf[off++] ^ x;                                      \
+      sz--;                                                            \
+    } while (sz);                                                      \
+  }                                                                    \
+                                                                       \
+  /* --- Done --- */                                                   \
+                                                                       \
+  ctx->off = off;                                                      \
+  return;                                                              \
+}                                                                      \
+                                                                       \
+/* --- Generic cipher interface --- */                                 \
+                                                                       \
+static const gcipher_ops gops;                                         \
+                                                                       \
+typedef struct gctx {                                                  \
+  gcipher c;                                                           \
+  pre##_counterctx k;                                                  \
+} gctx;                                                                        \
+                                                                       \
+static gcipher *ginit(const void *k, size_t sz)                                \
+{                                                                      \
+  gctx *g = S_CREATE(gctx);                                            \
+  g->c.ops = &gops;                                                    \
+  pre##_counterinit(&g->k, k, sz, 0);                                  \
+  return (&g->c);                                                      \
+}                                                                      \
+                                                                       \
+static void gencrypt(gcipher *c, const void *s, void *t, size_t sz)    \
+{                                                                      \
+  gctx *g = (gctx *)c;                                                 \
+  pre##_counterencrypt(&g->k, s, t, sz);                               \
+}                                                                      \
+                                                                       \
+static void gdestroy(gcipher *c)                                       \
+{                                                                      \
+  gctx *g = (gctx *)c;                                                 \
+  BURN(*g);                                                            \
+  S_DESTROY(g);                                                                \
+}                                                                      \
+                                                                       \
+static void gsetiv(gcipher *c, const void *iv)                         \
+{                                                                      \
+  gctx *g = (gctx *)c;                                                 \
+  pre##_countersetiv(&g->k, iv);                                       \
+}                                                                      \
+                                                                       \
+static void gbdry(gcipher *c)                                          \
+{                                                                      \
+  gctx *g = (gctx *)c;                                                 \
+  pre##_counterbdry(&g->k);                                            \
+}                                                                      \
+                                                                       \
+static const gcipher_ops gops = {                                      \
+  &pre##_counter,                                                      \
+  gencrypt, gencrypt, gdestroy, gsetiv, gbdry                          \
+};                                                                     \
+                                                                       \
+const gccipher pre##_counter = {                                       \
+  #pre "-counter", pre##_keysz, PRE##_BLKSZ,                           \
+  ginit                                                                        \
+};                                                                     \
+                                                                       \
+/* --- Generic random number generator interface --- */                        \
+                                                                       \
+typedef struct grctx {                                                 \
+  grand r;                                                             \
+  pre##_counterctx k;                                                  \
+} grctx;                                                               \
+                                                                       \
+static void grdestroy(grand *r)                                                \
+{                                                                      \
+  grctx *g = (grctx *)r;                                               \
+  BURN(*g);                                                            \
+  S_DESTROY(g);                                                                \
+}                                                                      \
+                                                                       \
+static int grmisc(grand *r, unsigned op, ...)                          \
+{                                                                      \
+  grctx *g = (grctx *)r;                                               \
+  va_list ap;                                                          \
+  int rc = 0;                                                          \
+  octet buf[PRE##_BLKSZ];                                              \
+  va_start(ap, op);                                                    \
+                                                                       \
+  switch (op) {                                                                \
+    case GRAND_CHECK:                                                  \
+      switch (va_arg(ap, unsigned)) {                                  \
+       case GRAND_CHECK:                                               \
+       case GRAND_SEEDINT:                                             \
+       case GRAND_SEEDUINT32:                                          \
+       case GRAND_SEEDBLOCK:                                           \
+       case GRAND_SEEDRAND:                                            \
+         rc = 1;                                                       \
+         break;                                                        \
+       default:                                                        \
+         rc = 0;                                                       \
+         break;                                                        \
+      }                                                                        \
+      break;                                                           \
+    case GRAND_SEEDINT:                                                        \
+      BLKC_SET(PRE, g->k.n, va_arg(ap, unsigned));                     \
+      g->k.off = PRE##_BLKSZ;                                          \
+      break;                                                           \
+    case GRAND_SEEDUINT32:                                             \
+      BLKC_SET(PRE, g->k.n, va_arg(ap, uint32));                       \
+      g->k.off = PRE##_BLKSZ;                                          \
+      break;                                                           \
+    case GRAND_SEEDBLOCK: {                                            \
+      const void *p = va_arg(ap, const void *);                                \
+      size_t sz = va_arg(ap, size_t);                                  \
+      if (sz < sizeof(buf)) {                                          \
+       memset(buf, 0, sizeof(buf));                                    \
+       memcpy(buf, p, sz);                                             \
+       p = buf;                                                        \
+      }                                                                        \
+      pre##_countersetiv(&g->k, p);                                    \
+    } break;                                                           \
+    case GRAND_SEEDRAND: {                                             \
+      grand *rr = va_arg(ap, grand *);                                 \
+      rr->ops->fill(rr, buf, sizeof(buf));                             \
+      pre##_countersetiv(&g->k, buf);                                  \
+    } break;                                                           \
+    default:                                                           \
+      GRAND_BADOP;                                                     \
+      break;                                                           \
+  }                                                                    \
+                                                                       \
+  va_end(ap);                                                          \
+  return (rc);                                                         \
+}                                                                      \
+                                                                       \
+static octet grbyte(grand *r)                                          \
+{                                                                      \
+  grctx *g = (grctx *)r;                                               \
+  octet o;                                                             \
+  pre##_counterencrypt(&g->k, 0, &o, 1);                               \
+  return (o);                                                          \
+}                                                                      \
+                                                                       \
+static uint32 grword(grand *r)                                         \
+{                                                                      \
+  grctx *g = (grctx *)r;                                               \
+  octet b[4];                                                          \
+  pre##_counterencrypt(&g->k, 0, b, sizeof(b));                                \
+  return (LOAD32(b));                                                  \
+}                                                                      \
+                                                                       \
+static void grfill(grand *r, void *p, size_t sz)                       \
+{                                                                      \
+  grctx *g = (grctx *)r;                                               \
+  pre##_counterencrypt(&g->k, 0, p, sz);                               \
+}                                                                      \
+                                                                       \
+static const grand_ops grops = {                                       \
+  #pre "-counter",                                                     \
+  GRAND_CRYPTO, 0,                                                     \
+  grmisc, grdestroy,                                                   \
+  grword, grbyte, grword, grand_range, grfill                          \
+};                                                                     \
+                                                                       \
+/* --- @pre_counterrand@ --- *                                         \
+ *                                                                     \
+ * Arguments:  @const void *k@ = pointer to key material               \
+ *             @size_t sz@ = size of key material                      \
+ *                                                                     \
+ * Returns:    Pointer to generic random number generator interface.   \
+ *                                                                     \
+ * Use:                Creates a random number interface wrapper around an     \
+ *             counter-mode block cipher.                              \
+ */                                                                    \
+                                                                       \
+grand *pre##_counterrand(const void *k, size_t sz)                     \
+{                                                                      \
+  grctx *g = S_CREATE(grctx);                                          \
+  g->r.ops = &grops;                                                   \
+  pre##_counterinit(&g->k, k, sz, 0);                                  \
+  return (&g->r);                                                      \
+}                                                                      \
+                                                                       \
+COUNTER_TEST(PRE, pre)
+
+/*----- Test rig ----------------------------------------------------------*/
+
+#ifdef TEST_RIG
+
+#include <stdio.h>
+
+#include "daftstory.h"
+
+/* --- @COUNTER_TEST@ --- *
+ *
+ * Arguments:  @PRE@, @pre@ = prefixes for block cipher definitions
+ *
+ * Use:                Standard test rig for counter functions.
+ */
+
+#define COUNTER_TEST(PRE, pre)                                         \
+                                                                       \
+/* --- Initial plaintext for the test --- */                           \
+                                                                       \
+static const octet text[] = TEXT;                                      \
+                                                                       \
+/* --- Key and IV to use --- */                                                \
+                                                                       \
+static const octet key[] = KEY;                                                \
+static const octet iv[] = IV;                                          \
+                                                                       \
+/* --- Buffers for encryption and decryption output --- */             \
+                                                                       \
+static octet ct[sizeof(text)];                                         \
+static octet pt[sizeof(text)];                                         \
+                                                                       \
+static void hexdump(const octet *p, size_t sz)                         \
+{                                                                      \
+  const octet *q = p + sz;                                             \
+  for (sz = 0; p < q; p++, sz++) {                                     \
+    printf("%02x", *p);                                                        \
+    if ((sz + 1) % PRE##_BLKSZ == 0)                                   \
+      putchar(':');                                                    \
+  }                                                                    \
+}                                                                      \
+                                                                       \
+int main(void)                                                         \
+{                                                                      \
+  size_t sz = 0, rest;                                                 \
+  pre##_counterctx ctx;                                                        \
+  int status = 0;                                                      \
+  int done = 0;                                                                \
+  pre##_ctx k;                                                         \
+                                                                       \
+  size_t keysz = PRE##_KEYSZ ?                                         \
+    PRE##_KEYSZ : strlen((const char *)key);                           \
+                                                                       \
+  fputs(#pre "-counter: ", stdout);                                    \
+                                                                       \
+  pre##_init(&k, key, keysz);                                          \
+  pre##_countersetkey(&ctx, &k);                                       \
+                                                                       \
+  while (sz <= sizeof(text)) {                                         \
+    rest = sizeof(text) - sz;                                          \
+    memcpy(ct, text, sizeof(text));                                    \
+    pre##_countersetiv(&ctx, iv);                                      \
+    pre##_counterencrypt(&ctx, ct, ct, sz);                            \
+    pre##_counterencrypt(&ctx, ct + sz, ct + sz, rest);                        \
+    memcpy(pt, ct, sizeof(text));                                      \
+    pre##_countersetiv(&ctx, iv);                                      \
+    pre##_counterencrypt(&ctx, pt, pt, rest);                          \
+    pre##_counterencrypt(&ctx, pt + rest, pt + rest, sz);              \
+    if (memcmp(pt, text, sizeof(text)) == 0) {                         \
+      done++;                                                          \
+      if (sizeof(text) < 40 || done % 8 == 0)                          \
+        fputc('.', stdout);                                            \
+      if (done % 480 == 0)                                             \
+        fputs("\n\t", stdout);                                         \
+      fflush(stdout);                                                  \
+    } else {                                                           \
+      printf("\nError (sz = %lu)\n", (unsigned long)sz);               \
+      status = 1;                                                      \
+      printf("\tplaintext      = "); hexdump(text, sz);                        \
+        printf(", "); hexdump(text + sz, rest);                                \
+        fputc('\n', stdout);                                           \
+      printf("\tciphertext     = "); hexdump(ct, sz);                  \
+        printf(", "); hexdump(ct + sz, rest);                          \
+        fputc('\n', stdout);                                           \
+      printf("\trecovered text = "); hexdump(pt, sz);                  \
+        printf(", "); hexdump(pt + sz, rest);                          \
+        fputc('\n', stdout);                                           \
+      fputc('\n', stdout);                                             \
+    }                                                                  \
+    if (sz < 63)                                                       \
+      sz++;                                                            \
+    else                                                               \
+      sz += 9;                                                         \
+  }                                                                    \
+                                                                       \
+  fputs(status ? " failed\n" : " ok\n", stdout);                       \
+  return (status);                                                     \
+}
+
+#else
+#  define COUNTER_TEST(PRE, pre)
+#endif
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+  }
+#endif
+
+#endif
diff --git a/counter.h b/counter.h
new file mode 100644 (file)
index 0000000..21211c7
--- /dev/null
+++ b/counter.h
@@ -0,0 +1,197 @@
+/* -*-c-*-
+ *
+ * $Id: counter.h,v 1.1 2000/06/17 10:51:42 mdw Exp $
+ *
+ * Block cipher counter mode (or long cycle mode)
+ *
+ * (c) 2000 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.
+ */
+
+/*----- Revision history --------------------------------------------------* 
+ *
+ * $Log: counter.h,v $
+ * Revision 1.1  2000/06/17 10:51:42  mdw
+ * Counter mode ciphers and pseudo-random generator.
+ *
+ */
+
+#ifndef CATACOMB_COUNTER_H
+#define CATACOMB_COUNTER_H
+
+#ifdef __cplusplus
+  extern "C" {
+#endif
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <stddef.h>
+
+#include <mLib/bits.h>
+
+#ifndef CATACOMB_GCIPHER_H
+#  include "gcipher.h"
+#endif
+
+#ifndef CATACOMB_GRAND_H
+#  include "grand.h"
+#endif
+
+/*----- Macros ------------------------------------------------------------*/
+
+/* --- @COUNTER_DECL@ --- *
+ *
+ * Arguments:  @PRE@, @pre@ = prefixes for block cipher definitions
+ *
+ * Use:                Makes declarations for counter mode.
+ */
+
+#define COUNTER_DECL(PRE, pre)                                         \
+                                                                       \
+/* --- Counter mode context --- */                                     \
+                                                                       \
+typedef struct pre##_counterctx {                                      \
+  pre##_ctx ctx;                       /* Underlying cipher context */ \
+  unsigned off;                                /* Current offset in buffer */  \
+  octet buf[PRE##_BLKSZ];              /* Output buffer */             \
+  uint32 n[PRE##_BLKSZ / 4];           /* Counter */                   \
+} pre##_counterctx;                                                    \
+                                                                       \
+/* --- @pre_countergetiv@ --- *                                                \
+ *                                                                     \
+ * Arguments:  @const pre_counterctx *ctx@ = pointer to counter        \
+ *                     context                                         \
+ *             @void *iv#@ = pointer to output data block              \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Reads the currently set IV.  Reading and setting an IV  \
+ *             is not transparent to the cipher.  It will add a `step' \
+ *             which must be matched by a similar operation during     \
+ *             decryption.                                             \
+ */                                                                    \
+                                                                       \
+extern void pre##_countergetiv(const pre##_counterctx */*ctx*/,                \
+                              void */*iv*/);                           \
+                                                                       \
+/* --- @pre_countersetiv@ --- *                                                \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to counter context      \
+ *             @cnost void *iv@ = pointer to IV to set                 \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Sets the IV to use for subsequent encryption.           \
+ */                                                                    \
+                                                                       \
+extern void pre##_countersetiv(pre##_counterctx */*ctx*/,              \
+                              const void */*iv*/);                     \
+                                                                       \
+/* --- @pre_counterbdry@ --- *                                         \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to counter context      \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Inserts a boundary during encryption.  Successful       \
+ *             decryption must place a similar boundary.               \
+ */                                                                    \
+                                                                       \
+extern void pre##_counterbdry(pre##_counterctx */*ctx*/);              \
+                                                                       \
+/* --- @pre_countersetkey@ --- *                                       \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to counter context      \
+ *             @const pre_ctx *k@ = pointer to cipher context          \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Sets the counter context to use a different cipher key. \
+ */                                                                    \
+                                                                       \
+extern void pre##_countersetkey(pre##_counterctx */*ctx*/,             \
+                               const pre##_ctx */*k*/);                \
+                                                                       \
+/* --- @pre_counterinit@ --- *                                         \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to cipher context       \
+ *             @const void *key@ = pointer to the key buffer           \
+ *             @size_t sz@ = size of the key                           \
+ *             @const void *iv@ = pointer to initialization vector     \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Initializes a counter context ready for use.  You       \
+ *             should ensure that the IV chosen is unique: reusing an  \
+ *             IV will compromise the security of the entire           \
+ *             plaintext.  This is equivalent to calls to @pre_init@,  \
+ *             @pre_countersetkey@ and @pre_countersetiv@.             \
+ */                                                                    \
+                                                                       \
+extern void pre##_counterinit(pre##_counterctx */*ctx*/,               \
+                             const void */*key*/, size_t /*sz*/,       \
+                         const void */*iv*/);                          \
+                                                                       \
+/* --- @pre_counterencrypt@ --- *                                      \
+ *                                                                     \
+ * Arguments:  @pre_counterctx *ctx@ = pointer to counter context      \
+ *             @const void *src@ = pointer to source data              \
+ *             @void *dest@ = pointer to destination data              \
+ *             @size_t sz@ = size of block to be encrypted             \
+ *                                                                     \
+ * Returns:    ---                                                     \
+ *                                                                     \
+ * Use:                Encrypts or decrypts a block with a block cipher in     \
+ *             counter mode: encryption and decryption are the same in \
+ *             counter.  The destination may be null to just churn the \
+ *             feedback round for a bit.  The source may be null to    \
+ *             use the cipher as a random data generator.              \
+ */                                                                    \
+                                                                       \
+extern void pre##_counterencrypt(pre##_counterctx */*ctx*/,            \
+                                const void */*src*/, void */*dest*/,   \
+                                size_t /*sz*/);                        \
+                                                                       \
+/* --- @pre_counterrand@ --- *                                         \
+ *                                                                     \
+ * Arguments:  @const void *k@ = pointer to key material               \
+ *             @size_t sz@ = size of key material                      \
+ *                                                                     \
+ * Returns:    Pointer to generic random number generator interface.   \
+ *                                                                     \
+ * Use:                Creates a random number interface wrapper around an     \
+ *             counter-mode block cipher.                              \
+ */                                                                    \
+                                                                       \
+extern grand *pre##_counterrand(const void */*k*/, size_t /*sz*/);     \
+                                                                       \
+/* --- Generic cipher interface --- */                                 \
+                                                                       \
+extern const gccipher pre##_counter;
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+  }
+#endif
+
+#endif