3 * Poly1305 message authentication code
5 * (c) 2017 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
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.
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.
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,
28 /*----- Notes on Poly1305 -------------------------------------------------*
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
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.
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.
50 #ifndef CATACOMB_POLY1305_H
51 #define CATACOMB_POLY1305_H
57 /*----- Header files ------------------------------------------------------*/
59 #include <mLib/bits.h>
61 #ifndef CATACOMB_KEYSZ_H
65 /*----- Constants ---------------------------------------------------------*/
67 extern const octet poly1305_keysz[];
69 #define POLY1305_BLKSZ 16u
70 #define POLY1305_KEYSZ 16u
71 #define POLY1305_MASKSZ 16u
72 #define POLY1305_TAGSZ 16u
74 /*----- Data structures ---------------------------------------------------*/
76 typedef struct poly1305_key {
78 struct { uint32 r0, r1, r2, r3, r4, rr1, rr2, rr3, rr4; } p26;
79 struct { uint16 r[12]; } p11;
83 typedef struct poly1305_ctx {
86 struct { uint32 s0, s1, s2, s3, s4; uint32 h[5]; } p26;
87 struct { uint16 s[12], h[12]; } p11;
94 /*----- Functions provided ------------------------------------------------*/
96 /* --- @poly1305_keyinit@ --- *
98 * Arguments: @poly1305_key *key@ = key structure to fill in
99 * @const void *k@ = pointer to key material
100 * @size_t ksz@ = length of key (must be @POLY1305_KEYSZ == 16@)
104 * Use: Records a Poly1305 key and performs (minimal)
108 extern void poly1305_keyinit(poly1305_key */*key*/,
109 const void */*k*/, size_t /*sz*/);
111 /* --- @poly1305_macinit@ --- *
113 * Arguments: @poly1305_ctx *ctx@ = MAC context to fill in
114 * @const poly1305_key *key@ = pointer to key structure to use
115 * @const void *iv@ = pointer to mask string
119 * Use: Initializes a MAC context for use. The key can be discarded
122 * It is permitted for @iv@ to be null, though it is not then
123 * possible to complete the MAC computation on @ctx@. The
124 * resulting context may still be useful, e.g., as an operand to
128 extern void poly1305_macinit(poly1305_ctx */*ctx*/,
129 const poly1305_key */*key*/,
132 /* --- @poly1305_copy@ --- *
134 * Arguments: @poly1305_ctx *to@ = destination context
135 * @const poly1305_ctx *from@ = source context
139 * Use: Duplicates a Poly1305 MAC context. The destination need not
140 * have been initialized. Both contexts can be used
141 * independently afterwards.
144 extern void poly1305_copy(poly1305_ctx */*to*/,
145 const poly1305_ctx */*from*/);
147 /* --- @poly1305_hash@ --- *
149 * Arguments: @poly1305_ctx *ctx@ = MAC context to update
150 * @const void *p@ = pointer to message data
151 * @size_t sz@ = length of message data
155 * Use: Processes a chunk of message. The message pieces may have
156 * arbitrary lengths, and may be empty.
159 extern void poly1305_hash(poly1305_ctx */*ctx*/,
160 const void */*p*/, size_t /*sz*/);
162 /* --- @poly1305_flush@ --- *
164 * Arguments: @poly1305_ctx *ctx@ = MAC context to flush
168 * Use: Forces any buffered message data in the context to be
169 * processed. This has no effect if the message processed so
170 * far is a whole number of blocks. Flushing is performed
171 * automatically by @poly1305_done@, but it may be necessary to
172 * force it by hand when using @poly1305_concat@.
174 * Flushing a partial block has an observable effect on the
175 * computation: the resulting state is (with high probability)
176 * dissimilar to any state reachable with a message which is a
177 * whole number of blocks long.
180 extern void poly1305_flush(poly1305_ctx */*ctx*/);
182 /* --- @poly1305_flushzero@ --- *
184 * Arguments: @poly1305_ctx *ctx@ = MAC context to flush
188 * Use: Forces any buffered message data in the context to be
189 * processed, by hashing between zero and fifteen additional
190 * zero bytes. Like @poly1305_flush@, this has no effect if the
191 * the message processed so far is a whole number of blocks.
192 * Unlike @poly1305_flush@, the behaviour if the message is not
193 * a whole number of blocks is equivalent to actually hashing
197 extern void poly1305_flushzero(poly1305_ctx */*ctx*/);
199 /* --- @poly1305_concat@ --- *
201 * Arguments: @poly1305_ctx *ctx@ = destination context
202 * @const poly1305_ctx *prefix, *suffix@ = two operand contexts
206 * Use: The two operand contexts @prefix@ and @suffix@ represent
207 * processing of two messages %$m$% and %$m'$%; the effect is to
208 * set @ctx@ to the state corresponding to their concatenation
211 * All three contexts must have been initialized using the same
212 * key value (though not necessarily from the same key
213 * structure). The mask values associated with the input
214 * contexts are irrelevant. The @prefix@ message %$m$% must be
215 * a whole number of blocks long: this can be arranged by
216 * flushing the context. The @suffix@ message need not be a
217 * whole number of blocks long. All of the contexts remain
218 * operational and can be used independently afterwards.
221 extern void poly1305_concat(poly1305_ctx */*ctx*/,
222 const poly1305_ctx */*prefix*/,
223 const poly1305_ctx */*suffix*/);
225 /* --- @poly1305_done@ --- *
227 * Arguments: @poly1305_ctx *ctx@ = MAC context to finish
228 * @void *h@ = buffer to write the tag to
232 * Use: Completes a Poly1305 MAC tag computation.
235 extern void poly1305_done(poly1305_ctx */*ctx*/, void */*h*/);
237 /*----- That's all, folks -------------------------------------------------*/