Commit | Line | Data |
---|---|---|
57496a50 MW |
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 |