chiark - git - mdw - catacomb/blob - symm/poly1305.h

   1 /* -*-c-*-
   2  *
   3  * Poly1305 message authentication code
   4  *
   5  * (c) 2017 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of Catacomb.
  11  *
  12  * Catacomb is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * Catacomb is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with Catacomb; if not, write to the Free
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 /*----- Notes on Poly1305 -------------------------------------------------*
  29  *
  30  * The Poly1305 message authentication code was designed by Daniel Bernstein
  31  * in 2004.  It's a heavily performance-engineered Carter--Wegman MAC, based
  32  * on polynomial evaluation in %$\F = \mathrm{GF}(2^{130} - 5)$%.  Some of
  33  * the performance engineering is out-of-date, being there to support
  34  * implementation techniques which are no longer relevant, but it still runs
  35  * very quickly.
  36  *
  37  * The key %$r$% is an element of %$\F$%.  Messages are encoded as a sequence
  38  * %$m_0, m_1, \ldots, m_{n-1}$% of of elements of %$\F$%.  A raw hash is
  39  * calculated as %$h_0 = \sum_{0\le i<n} m_0 r^{n-i}$%.  Finally, the raw
  40  * hash is masked for output by adding to its canonical representative a mask
  41  * value %$s$% modulo %$2^{128}$% and encoding the result as an octet string.
  42  *
  43  * As originally presented, Poly1305 generated the output mask by encrypting
  44  * a nonce using AES.  This has since been separated from the design, so that
  45  * Poly1305 stands on its own.  Poly1305 is highly key-agile, and most modern
  46  * uses simply generate a fresh pseudorandom key and mask for each message.
  47  * Note that both key and mask must be (at least) pseudorandom.
  48  */
  49
  50 #ifndef CATACOMB_POLY1305_H
  51 #define CATACOMB_POLY1305_H
  52
  53 #ifdef __cplusplus
  54   extern "C" {
  55 #endif
  56
  57 /*----- Header files ------------------------------------------------------*/
  58
  59 #include <mLib/bits.h>
  60
  61 #ifndef CATACOMB_KEYSZ_H
  62 #  include "keysz.h"
  63 #endif
  64
  65 /*----- Constants ---------------------------------------------------------*/
  66
  67 extern const octet poly1305_keysz[];
  68
  69 #define POLY1305_BLKSZ 16u
  70 #define POLY1305_KEYSZ 16u
  71 #define POLY1305_MASKSZ 16u
  72
  73 /*----- Data structures ---------------------------------------------------*/
  74
  75 typedef struct poly1305_key {
  76   union {
  77     struct { uint32 r0, r1, r2, r3, r4, rr1, rr2, rr3, rr4; } p26;
  78     struct { uint16 r[12]; } p11;
  79   } u;
  80 } poly1305_key;
  81
  82 typedef struct poly1305_ctx {
  83   poly1305_key k;
  84   union {
  85     struct { uint32 s0, s1, s2, s3, s4; uint32 h[5]; } p26;
  86     struct { uint16 s[12], h[12]; } p11;
  87   } u;
  88   unsigned long count;
  89   unsigned nbuf;
  90   octet buf[16];
  91 } poly1305_ctx;
  92
  93 /*----- Functions provided ------------------------------------------------*/
  94
  95 /* --- @poly1305_keyinit@ --- *
  96  *
  97  * Arguments:   @poly1305_key *key@ = key structure to fill in
  98  *              @const void *k@ = pointer to key material
  99  *              @size_t ksz@ = length of key (must be @POLY1305_KEYSZ == 16@)
 100  *
 101  * Returns:     ---
 102  *
 103  * Use:         Records a Poly1305 key and performs (minimal)
 104  *              precomputations.
 105  */
 106
 107 extern void poly1305_keyinit(poly1305_key */*key*/,
 108                              const void */*k*/, size_t /*sz*/);
 109
 110 /* --- @poly1305_macinit@ --- *
 111  *
 112  * Arguments:   @poly1305_ctx *ctx@ = MAC context to fill in
 113  *              @const poly1305_key *key@ = pointer to key structure to use
 114  *              @const void *iv@ = pointer to mask string
 115  *
 116  * Returns:     ---
 117  *
 118  * Use:         Initializes a MAC context for use.  The key can be discarded
 119  *              at any time.
 120  *
 121  *              It is permitted for @iv@ to be null, though it is not then
 122  *              possible to complete the MAC computation on @ctx@.  The
 123  *              resulting context may still be useful, e.g., as an operand to
 124  *              @poly1305_concat@.
 125  */
 126
 127 extern void poly1305_macinit(poly1305_ctx */*ctx*/,
 128                              const poly1305_key */*key*/,
 129                              const void */*iv*/);
 130
 131 /* --- @poly1305_copy@ --- *
 132  *
 133  * Arguments:   @poly1305_ctx *to@ = destination context
 134  *              @const poly1305_ctx *from@ = source context
 135  *
 136  * Returns:     ---
 137  *
 138  * Use:         Duplicates a Poly1305 MAC context.  The destination need not
 139  *              have been initialized.  Both contexts can be used
 140  *              independently afterwards.
 141  */
 142
 143 extern void poly1305_copy(poly1305_ctx */*to*/,
 144                           const poly1305_ctx */*from*/);
 145
 146 /* --- @poly1305_hash@ --- *
 147  *
 148  * Arguments:   @poly1305_ctx *ctx@ = MAC context to update
 149  *              @const void *p@ = pointer to message data
 150  *              @size_t sz@ = length of message data
 151  *
 152  * Returns:     ---
 153  *
 154  * Use:         Processes a chunk of message.  The message pieces may have
 155  *              arbitrary lengths, and may be empty.
 156  */
 157
 158 extern void poly1305_hash(poly1305_ctx */*ctx*/,
 159                           const void */*p*/, size_t /*sz*/);
 160
 161 /* --- @poly1305_flush@ --- *
 162  *
 163  * Arguments:   @poly1305_ctx *ctx@ = MAC context to flush
 164  *
 165  * Returns:     ---
 166  *
 167  * Use:         Forces any buffered message data in the context to be
 168  *              processed.  This has no effect if the message processed so
 169  *              far is a whole number of blocks.  Flushing is performed
 170  *              automatically by @poly1305_done@, but it may be necessary to
 171  *              force it by hand when using @poly1305_concat@.
 172  *
 173  *              Flushing a partial block has an observable effect on the
 174  *              computation: the resulting state is (with high probability)
 175  *              dissimilar to any state reachable with a message which is a
 176  *              whole number of blocks long.
 177  */
 178
 179 extern void poly1305_flush(poly1305_ctx */*ctx*/);
 180
 181 /* --- @poly1305_concat@ --- *
 182  *
 183  * Arguments:   @poly1305_ctx *ctx@ = destination context
 184  *              @const poly1305_ctx *prefix, *suffix@ = two operand contexts
 185  *
 186  * Returns:     ---
 187  *
 188  * Use:         The two operand contexts @prefix@ and @suffix@ represent
 189  *              processing of two messages %$m$% and %$m'$%; the effect is to
 190  *              set @ctx@ to the state corresponding to their concatenation
 191  *              %$m \cat m'$%.
 192  *
 193  *              All three contexts must have been initialized using the same
 194  *              key value (though not necessarily from the same key
 195  *              structure).  The mask values associated with the input
 196  *              contexts are irrelevant.  The @prefix@ message %$m$% must be
 197  *              a whole number of blocks long: this can be arranged by
 198  *              flushing the context.  The @suffix@ message need not be a
 199  *              whole number of blocks long.  All of the contexts remain
 200  *              operational and can be used independently afterwards.
 201  */
 202
 203 extern void poly1305_concat(poly1305_ctx */*ctx*/,
 204                             const poly1305_ctx */*prefix*/,
 205                             const poly1305_ctx */*suffix*/);
 206
 207 /* --- @poly1305_done@ --- *
 208  *
 209  * Arguments:   @poly1305_ctx *ctx@ = MAC context to finish
 210  *              @void *h@ = buffer to write the tag to
 211  *
 212  * Returns:     ---
 213  *
 214  * Use:         Completes a Poly1305 MAC tag computation.
 215  */
 216
 217 extern void poly1305_done(poly1305_ctx */*ctx*/, void */*h*/);
 218
 219 /*----- That's all, folks -------------------------------------------------*/
 220
 221 #ifdef __cplusplus
 222   }
 223 #endif
 224
 225 #endif