~mdw / catacomb / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
progs/perftest.c: Use from Glibc syscall numbers.
[catacomb] / symm / gcm.h
1 /* -*-c-*-
2 *
3 * The GCM authenticated encryption mode
4 *
5 * (c) 2018 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 it
13 * under the terms of the GNU Library General Public License as published
14 * by the Free Software Foundation; either version 2 of the License, or
15 * (at your option) any later version.
16 *
17 * Catacomb is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * 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 Software
24 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
25 * USA.
26 */
27
28 /*----- Notes on GCM ------------------------------------------------------*
29 *
30 * The name is short for `Galois Counter Mode'. GCM was designed in 2005 by
31 * David McGrew and John Viega as a fast, patent-free authenticated
32 * encryption scheme; and it's specified by NIST in SP800-38D. It combines
33 * counter-mode encryption with a Carter--Wegman authenticator based on a
34 * polynomial hash over %$\gf{2^{128}}%, so it needs only one blockcipher
35 * application per message block, together with a multiplication by a
36 * constant in the finite field. GCM is essentially the winner in the
37 * authenticated-encryption-mode competition, to the extent that Intel and
38 * ARM both added instructions to their architectures to accelerate it.
39 *
40 * GCM allows arbitrary-sized nonces, though it's happiest if the nonce is 32
41 * bits shorter than the block size, leaving a fixed-size block counter in
42 * the low 32 bits. It permits header data to be processed independently of
43 * the message, though doing this requires some slightly fiddly algebra and
44 * most implementations don't allow callers to take advantage of this.
45 *
46 * One downside is that the field multiplication is inefficient in software.
47 * Back in 2005 it was assumed that implementors would use large tables, but
48 * that leaks the authentication secret through the processor cache. This
49 * implementation runs in constant time, but the penalty is that, without
50 * dedicated processor support, it's much slower than an extra blockcipher
51 * application would have been.
52 *
53 * Another downside is that, while GCM came with a security proof, it was
54 * subtly incorrect in a few ways which mean that its concrete security is
55 * significantly less than one would expect.
56 *
57 * If interoperability isn't a concern, then OCB3 is probably a better
58 * choice; if the OCB patent situation is also worrying, then EAX is likely
59 * preferable.
60 */
61
62 #ifndef CATACOMB_GCM_H
63 #define CATACOMB_GCM_H
64
65 #ifdef __cplusplus
66 extern "C" {
67 #endif
68
69 /*----- Header files ------------------------------------------------------*/
70
71 #include <stddef.h>
72
73 #include <mLib/bits.h>
74 #include <mLib/buf.h>
75
76 #ifndef CATACOMB_GAEAD_H
77 # include "gaead.h"
78 #endif
79
80 /*----- Macros ------------------------------------------------------------*/
81
82 /* --- @GCM_DECL@ --- *
83 *
84 * Arguments: @PRE@, @pre@ = prefixes for the underlying block cipher
85 *
86 * Use: Creates declarations for GCM authenticated-encryption mode.
87 */
88
89 #define GCM_DECL(PRE, pre) \
90 \
91 typedef struct pre##_gcmkey { \
92 pre##_ctx ctx; /* Block cipher key */ \
93 uint32 ktab[32*PRE##_BLKSZ*PRE##_BLKSZ]; /* Multiplication table */ \
94 } pre##_gcmkey; \
95 \
96 typedef struct pre##_gcmaadctx { \
97 pre##_gcmkey k; /* Underlying key */ \
98 uint32 a[PRE##_BLKSZ/4]; /* GHASH accumulator */ \
99 octet b[PRE##_BLKSZ]; /* Input buffer */ \
100 unsigned off; /* Length of stuff in buffer */ \
101 unsigned long len; /* Number of blocks so far */ \
102 } pre##_gcmaadctx; \
103 \
104 typedef struct pre##_gcmctx { \
105 /* The buffer is split into two portions. The first N octets hold a \
106 * chunk of ciphertext, which will be fed into the OMAC calculation; \
107 * the remaining BLKSZ - N octets hold E_K(C), which is the XOR mask \
108 * to apply to the plaintext or ciphertext. \
109 */ \
110 pre##_gcmkey k; /* Underlying key */ \
111 uint32 c[PRE##_BLKSZ/4]; /* Current counter value */ \
112 uint32 c0[PRE##_BLKSZ/4]; /* Initial counter */ \
113 uint32 a[PRE##_BLKSZ]; /* GHASH accumulator */ \
114 octet b[PRE##_BLKSZ]; /* Ciphertext/mask buffer */ \
115 unsigned off; /* Crossover point in buffer */ \
116 unsigned long len; /* Number of blocks so far */ \
117 } pre##_gcmctx; \
118 \
119 extern const octet pre##_gcmnoncesz[], pre##_gcmtagsz[]; \
120 \
121 /* --- @pre_gcmsetkey@ --- * \
122 * \
123 * Arguments: @pre_gcmkey *key@ = pointer to key block to fill in \
124 * @const void *k@ = pointer to key material \
125 * @size_t ksz@ = size of key material \
126 * \
127 * Returns: --- \
128 * \
129 * Use: Initializes an GCM key block. \
130 */ \
131 \
132 extern void pre##_gcmsetkey(pre##_gcmkey */*key*/, \
133 const void */*k*/, size_t /*ksz*/); \
134 \
135 /* --- @pre_gcmaadinit@ --- * \
136 * \
137 * Arguments: @pre_gcmaadctx *aad@ = pointer to AAD context \
138 * @const pre_gcmkey *key@ = pointer to key block \
139 * \
140 * Returns: --- \
141 * \
142 * Use: Initializes an GCM AAD (`additional authenticated \
143 * data') context associated with a given key. AAD \
144 * contexts can be copied and/or reused, saving time if \
145 * the AAD for a number of messages has a common prefix. \
146 * \
147 * The @key@ doesn't need to be kept around, though \
148 * usually there'll at least be another copy in some GCM \
149 * operation context because the AAD on its own isn't much \
150 * good. \
151 */ \
152 \
153 extern void pre##_gcmaadinit(pre##_gcmaadctx */*aad*/, \
154 const pre##_gcmkey */*key*/); \
155 \
156 /* --- @pre_gcmaadhash@ --- * \
157 * \
158 * Arguments: @pre_gcmaadctx *aad@ = pointer to AAD context \
159 * @const void *p@ = pointer to AAD material \
160 * @size_t sz@ = length of AAD material \
161 * \
162 * Returns: --- \
163 * \
164 * Use: Feeds AAD into the context. \
165 */ \
166 \
167 extern void pre##_gcmaadhash(pre##_gcmaadctx */*aad*/, \
168 const void */*p*/, size_t /*sz*/); \
169 \
170 /* --- @pre_gcminit@ --- * \
171 * \
172 * Arguments: @pre_gcmctx *ctx@ = pointer to GCM context \
173 * @const pre_gcmkey *key@ = pointer to key block \
174 * @const void *n@ = pointer to nonce \
175 * @size_t nsz@ = size of nonce \
176 * \
177 * Returns: --- \
178 * \
179 * Use: Initialize an GCM operation context with a given key. \
180 * \
181 * The original key needn't be kept around any more. \
182 */ \
183 \
184 extern void pre##_gcminit(pre##_gcmctx */*ctx*/, \
185 const pre##_gcmkey */*k*/, \
186 const void */*n*/, size_t /*nsz*/); \
187 \
188 /* --- @pre_gcmreinit@ --- * \
189 * \
190 * Arguments: @pre_gcmctx *ctx@ = pointer to GCM context \
191 * @const void *n@ = pointer to nonce \
192 * @size_t nsz@ = size of nonce \
193 * \
194 * Returns: --- \
195 * \
196 * Use: Reinitialize an GCM operation context, changing the \
197 * nonce. \
198 */ \
199 \
200 extern void pre##_gcmreinit(pre##_gcmctx */*ctx*/, \
201 const void */*n*/, size_t /*nsz*/); \
202 \
203 /* --- @pre_gcmencrypt@ --- * \
204 * \
205 * Arguments: @pre_gcmctx *ctx@ = pointer to GCM operation context \
206 * @const void *src@ = pointer to plaintext message chunk \
207 * @size_t sz@ = size of the plaintext \
208 * @buf *dst@ = a buffer to write the ciphertext to \
209 * \
210 * Returns: Zero on success; @-1@ on failure. \
211 * \
212 * Use: Encrypts a chunk of a plaintext message, writing a \
213 * chunk of ciphertext to the output buffer and updating \
214 * the operation state. \
215 * \
216 * For GCM, we always write a ciphertext chunk the same \
217 * size as the plaintext. The messing about with @buf@ \
218 * objects makes the interface consistent with other AEAD \
219 * schemes which can't do this. \
220 */ \
221 \
222 extern int pre##_gcmencrypt(pre##_gcmctx */*ctx*/, \
223 const void */*src*/, size_t /*sz*/, \
224 buf */*dst*/); \
225 \
226 /* --- @pre_gcmdecrypt@ --- * \
227 * \
228 * Arguments: @pre_gcmctx *ctx@ = pointer to GCM operation context \
229 * @const void *src@ = pointer to ciphertext message chunk \
230 * @size_t sz@ = size of the ciphertext \
231 * @buf *dst@ = a buffer to write the plaintext to \
232 * \
233 * Returns: Zero on success; @-1@ on failure. \
234 * \
235 * Use: Decrypts a chunk of a ciphertext message, writing a \
236 * chunk of plaintext to the output buffer and updating \
237 * the operation state. \
238 * \
239 * For GCM, we always write a plaintext chunk the same \
240 * size as the ciphertext. The messing about with @buf@ \
241 * objects makes the interface consistent with other AEAD \
242 * schemes which can't do this. \
243 */ \
244 \
245 extern int pre##_gcmdecrypt(pre##_gcmctx */*ctx*/, \
246 const void */*src*/, size_t /*sz*/, \
247 buf */*dst*/); \
248 \
249 /* --- @pre_gcmencryptdone@ --- * \
250 * \
251 * Arguments: @pre_gcmctx *ctx@ = pointer to an GCM context \
252 * @const pre_gcmaadctx *aad@ = pointer to AAD context, or \
253 * null \
254 * @buf *dst@ = buffer for remaining ciphertext \
255 * @void *tag@ = where to write the tag \
256 * @size_t tsz@ = length of tag to store \
257 * \
258 * Returns: Zero on success; @-1@ on failure. \
259 * \
260 * Use: Completes an GCM encryption operation. The @aad@ \
261 * pointer may be null if there is no additional \
262 * authenticated data. GCM doesn't buffer ciphertext, but \
263 * the output buffer is provided anyway for consistency \
264 * with other AEAD schemes which don't have this property; \
265 * the function will fail if the output buffer is broken. \
266 */ \
267 \
268 extern int pre##_gcmencryptdone(pre##_gcmctx */*ctx*/, \
269 const pre##_gcmaadctx */*aad*/, \
270 buf */*dst*/, \
271 void */*tag*/, size_t /*tsz*/); \
272 \
273 /* --- @pre_gcmdecryptdone@ --- * \
274 * \
275 * Arguments: @pre_gcmctx *ctx@ = pointer to an GCM context \
276 * @const pre_gcmaadctx *aad@ = pointer to AAD context, or \
277 * null \
278 * @buf *dst@ = buffer for remaining plaintext \
279 * @const void *tag@ = tag to verify \
280 * @size_t tsz@ = length of tag \
281 * \
282 * Returns: @+1@ for complete success; @0@ if tag verification \
283 * failed; @-1@ for other kinds of errors. \
284 * \
285 * Use: Completes an GCM decryption operation. The @aad@ \
286 * pointer may be null if there is no additional \
287 * authenticated data. GCM doesn't buffer plaintext, but \
288 * the output buffer is provided anyway for consistency \
289 * with other AEAD schemes which don't have this property; \
290 * the function will fail if the output buffer is broken. \
291 */ \
292 \
293 extern int pre##_gcmdecryptdone(pre##_gcmctx */*ctx*/, \
294 const pre##_gcmaadctx */*aad*/, \
295 buf */*dst*/, \
296 const void */*tag*/, size_t /*tsz*/); \
297 \
298 /* --- Generic AEAD interface --- */ \
299 \
300 extern const gcaead pre##_gcm;
301
302 /*----- That's all, folks -------------------------------------------------*/
303
304 #ifdef __cplusplus
305 }
306 #endif
307
308 #endif
Catacomb cryptographic library