Commit | Line | Data |
---|---|---|
b39fadb6 MW |
1 | /* -*-c-*- |
2 | * | |
3 | * The OCB1 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 OCB1 -----------------------------------------------------* | |
29 | * | |
30 | * OCB was designed in 2001 by Phillip Rogaway, with Mihir Bellare and John | |
31 | * Black, as a blockcipher-based authenticated encryption scheme which can | |
32 | * operate on multiple message blocks in parallel and requires only a single | |
33 | * blockcipher application per message block. It refines Charanjit Jutla's | |
34 | * earlier IAPM, which was the first such mode to be proven secure. This | |
35 | * version implements the `OCB.PMAC' mode described by Rogaway in 2002, which | |
36 | * combines the original OCB with PMAC (Rogaway and Black, 2002) into a | |
37 | * single authenticated-encryption with associated-data (AEAD) scheme. | |
38 | * | |
39 | * The patent situation on these efficient authenticated encryption schemes | |
40 | * is fraught. IBM hold two patents on Jutla's pioneering work on `IACBC' | |
41 | * and `IAPM' which can apply (a third was filed at least six years too | |
42 | * late), and Virgil Gligor and Pompiliu Donescu hold patents on their `XECB' | |
43 | * and `XCBC' modes; these may or may not apply to OCB. Rogaway himself | |
44 | * holds US patents on various versions of OCB, but has issued free licences | |
45 | * for free (`open source') software, and for all non-military use. I think | |
46 | * Catacomb's implementation of OCB falls within the scope of the former | |
47 | * licence. | |
48 | * | |
49 | * Confusingly, Rogaway's 2004 paper `Efficient Instantiations of Tweakable | |
50 | * Blockciphers and Refinements to Modes OCB and PMAC' named the new versions | |
51 | * of those modes `OCB1' and `PMAC1'. The 2011 paper by Krovetz and Rogaway, | |
52 | * `The Software Performance of Authenticated-Encryption Modes' renamed the | |
53 | * original 2001 version of OCB as `OCB1', and the 2004 version `OCB2', and | |
54 | * introduced a new `OCB3'. I've decided to follow and extend the 2011 | |
55 | * naming, so `OCB1' refers to the 2001 OCB; the 2004 version would be | |
56 | * `OCB2'. | |
57 | * | |
58 | * The OCB specification is clear about how OCB applies to arbitrary block | |
59 | * sizes. | |
60 | * | |
61 | * OCB1 is a fairly well-behaved AEAD mode. It doesn't require | |
62 | * precommentment to any lengths, and allows header data to be processed | |
63 | * independently of any message. On the other hand, it only accepts nonces | |
64 | * the same size as the underlying blockcipher's block size, and it buffers | |
65 | * up to a whole block's worth of data internally, which somewhat complicates | |
66 | * streaming. | |
67 | */ | |
68 | ||
69 | #ifndef CATACOMB_OCB1_H | |
70 | #define CATACOMB_OCB1_H | |
71 | ||
72 | #ifdef __cplusplus | |
73 | extern "C" { | |
74 | #endif | |
75 | ||
76 | /*----- Header files ------------------------------------------------------*/ | |
77 | ||
78 | #include <stddef.h> | |
79 | ||
80 | #include <mLib/bits.h> | |
81 | #include <mLib/buf.h> | |
82 | ||
83 | #ifndef CATACOMB_GAEAD_H | |
84 | # include "gaead.h" | |
85 | #endif | |
86 | ||
87 | #ifndef CATACOMB_OCB_H | |
88 | # include "ocb.h" | |
89 | #endif | |
90 | ||
91 | #ifndef CATACOMB_RSVR_H | |
92 | # include "rsvr.h" | |
93 | #endif | |
94 | ||
95 | /*----- Macros ------------------------------------------------------------*/ | |
96 | ||
97 | /* --- @OCB1_DECL@ --- * | |
98 | * | |
99 | * Arguments: @PRE@, @pre@ = prefixes for the underlying block cipher | |
100 | * | |
101 | * Use: Creates declarations for OCB1 message-authentication mode. | |
102 | */ | |
103 | ||
104 | #define OCB1_STRUCTS(PRE, pre, keyty, aadty) \ | |
105 | \ | |
106 | typedef struct keyty { \ | |
107 | pre##_ctx ctx; /* Underlying cipher context */ \ | |
108 | uint32 lxinv[PRE##_BLKSZ/4]; /* Final-block mask */ \ | |
109 | uint32 lmask[OCB_NCALC][PRE##_BLKSZ/4]; /* Precalculated masks */ \ | |
110 | } keyty; \ | |
111 | \ | |
112 | typedef struct aadty { \ | |
113 | keyty k; /* Processed key material */ \ | |
114 | uint32 o[PRE##_BLKSZ/4]; /* Current offset */ \ | |
115 | uint32 a[PRE##_BLKSZ/4]; /* Accumulator state */ \ | |
116 | octet b[PRE##_BLKSZ]; /* Input buffer */ \ | |
117 | unsigned long i; /* Block counter */ \ | |
118 | unsigned off; /* Offset into buffered data */ \ | |
119 | } aadty; | |
120 | ||
121 | #define OCB1_DECL(PRE, pre) \ | |
122 | \ | |
123 | OCB1_STRUCTS(PRE, pre, pre##_ocb1key, pre##_ocb1aadctx) \ | |
124 | \ | |
125 | typedef struct pre##_ocb1ctx { \ | |
126 | /* This is the same as @pre_ocb1aadctx@ above, but the two are \ | |
127 | * logically distinct and shouldn't be muddled up. \ | |
128 | */ \ | |
129 | \ | |
130 | pre##_ocb1key k; /* Processed key material */ \ | |
131 | uint32 o[PRE##_BLKSZ/4]; /* Current offset */ \ | |
132 | uint32 a[PRE##_BLKSZ/4]; /* Accumulator state */ \ | |
133 | octet b[PRE##_BLKSZ]; /* Input buffer */ \ | |
134 | unsigned long i; /* Block counter */ \ | |
135 | unsigned off; /* Offset into buffered data */ \ | |
136 | } pre##_ocb1ctx; \ | |
137 | \ | |
138 | extern const rsvr_policy pre##_ocb1policy; \ | |
139 | \ | |
140 | extern const octet pre##_ocb1noncesz[], pre##_ocb1tagsz[]; \ | |
141 | \ | |
142 | /* --- @pre_ocb1setkey@ --- * \ | |
143 | * \ | |
144 | * Arguments: @pre_ocb1key *key@ = pointer to key block to fill in \ | |
145 | * @const void *k@ = pointer to key material \ | |
146 | * @size_t ksz@ = size of key material \ | |
147 | * \ | |
148 | * Returns: --- \ | |
149 | * \ | |
150 | * Use: Initializes an OCB1 key block. \ | |
151 | */ \ | |
152 | \ | |
153 | extern void pre##_ocb1setkey(pre##_ocb1key */*key*/, \ | |
154 | const void */*k*/, size_t /*ksz*/); \ | |
155 | \ | |
156 | /* --- @pre_ocb1aadinit@ --- * \ | |
157 | * \ | |
158 | * Arguments: @pre_ocb1aadctx *aad@ = pointer to AAD context \ | |
159 | * @const pre_ocb1key *key@ = pointer to key block \ | |
160 | * \ | |
161 | * Returns: --- \ | |
162 | * \ | |
163 | * Use: Initializes an OCB1 AAD (`additional authenticated \ | |
164 | * data') context associated with a given key. AAD \ | |
165 | * contexts can be copied and/or reused, saving time if \ | |
166 | * the AAD for number of messages has a common prefix. \ | |
167 | * \ | |
168 | * The @key@ doesn't need to be kept around, though \ | |
169 | * usually there'll at least be another copy in some OCB1 \ | |
170 | * operation context because the AAD on its own isn't much \ | |
171 | * good. \ | |
172 | */ \ | |
173 | \ | |
174 | extern void pre##_ocb1aadinit(pre##_ocb1aadctx */*aad*/, \ | |
175 | const pre##_ocb1key */*key*/); \ | |
176 | \ | |
177 | /* --- @pre_ocb1aadhash@ --- * \ | |
178 | * \ | |
179 | * Arguments: @pre_ocb1aadctx *aad@ = pointer to AAD context \ | |
180 | * @const void *p@ = pointer to AAD material \ | |
181 | * @size_t sz@ = length of AAD material \ | |
182 | * \ | |
183 | * Returns: --- \ | |
184 | * \ | |
185 | * Use: Feeds AAD into the context. \ | |
186 | */ \ | |
187 | \ | |
188 | extern void pre##_ocb1aadhash(pre##_ocb1aadctx */*aad*/, \ | |
189 | const void */*p*/, size_t /*sz*/); \ | |
190 | \ | |
191 | /* --- @pre_ocb1aadtag@ --- * \ | |
192 | * \ | |
193 | * Arguments: @const pre_ocb1aadctx *aad@ = pointer to context block \ | |
194 | * @uint32 *u@ = where to write the tag \ | |
195 | * \ | |
196 | * Returns: --- \ | |
197 | * \ | |
198 | * Use: Finishes processing AAD and produces a tag which can be \ | |
199 | * mixed with an OCB1 checksum. This function is exposed \ | |
200 | * for internal reasons and is not expected to be \ | |
201 | * generally useful. \ | |
202 | */ \ | |
203 | \ | |
204 | extern void pre##_ocb1aadtag(const pre##_ocb1aadctx */*aad*/, \ | |
205 | uint32 */*t*/); \ | |
206 | \ | |
207 | /* --- @pre_ocb1init@ --- * \ | |
208 | * \ | |
209 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to OCB1 context \ | |
210 | * @const pre_ocb1key *key@ = pointer to key block \ | |
211 | * @const void *n@ = pointer to nonce \ | |
212 | * @size_t nsz@ = size of nonce \ | |
213 | * \ | |
214 | * Returns: Zero on success, @-1@ if the nonce length is bad. \ | |
215 | * \ | |
216 | * Use: Initialize an OCB1 operation context with a given key. \ | |
217 | * \ | |
218 | * The original key needn't be kept around any more. \ | |
219 | */ \ | |
220 | \ | |
221 | extern int pre##_ocb1init(pre##_ocb1ctx */*ctx*/, \ | |
222 | const pre##_ocb1key */*k*/, \ | |
223 | const void */*n*/, size_t /*nsz*/); \ | |
224 | \ | |
225 | /* --- @pre_ocb1reinit@ --- * \ | |
226 | * \ | |
227 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to OCB1 context \ | |
228 | * @const void *n@ = pointer to nonce \ | |
229 | * @size_t nsz@ = size of nonce \ | |
230 | * \ | |
231 | * Returns: Zero on success, @-1@ if the nonce length is bad. \ | |
232 | * \ | |
233 | * Use: Reinitialize an OCB1 operation context, changing the \ | |
234 | * nonce. \ | |
235 | */ \ | |
236 | \ | |
237 | extern int pre##_ocb1reinit(pre##_ocb1ctx */*ctx*/, \ | |
238 | const void */*n*/, size_t /*nsz*/); \ | |
239 | \ | |
240 | /* --- @pre_ocb1encrypt@ --- * \ | |
241 | * \ | |
242 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to OCB1 operation context \ | |
243 | * @const void *src@ = pointer to plaintext message chunk \ | |
244 | * @size_t sz@ = size of the plaintext \ | |
245 | * @buf *dst@ = a buffer to write the ciphertext to \ | |
246 | * \ | |
247 | * Returns: Zero on success; @-1@ on failure. \ | |
248 | * \ | |
249 | * Use: Encrypts a chunk of a plaintext message, writing a \ | |
250 | * chunk of ciphertext to the output buffer and updating \ | |
251 | * the operation state. \ | |
252 | * \ | |
253 | * Note that OCB1 delays output if its input is not a \ | |
254 | * whole number of blocks. This means that the output \ | |
255 | * might be smaller or larger the input by up to the block \ | |
256 | * size. \ | |
257 | */ \ | |
258 | \ | |
259 | extern int pre##_ocb1encrypt(pre##_ocb1ctx */*ctx*/, \ | |
260 | const void */*src*/, size_t /*sz*/, \ | |
261 | buf */*dst*/); \ | |
262 | \ | |
263 | /* --- @pre_ocb1decrypt@ --- * \ | |
264 | * \ | |
265 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to OCB1 operation context \ | |
266 | * @const void *src@ = pointer to ciphertext message chunk \ | |
267 | * @size_t sz@ = size of the ciphertext \ | |
268 | * @buf *dst@ = a buffer to write the plaintext to \ | |
269 | * \ | |
270 | * Returns: Zero on success; @-1@ on failure. \ | |
271 | * \ | |
272 | * Use: Decrypts a chunk of a ciphertext message, writing a \ | |
273 | * chunk of plaintext to the output buffer and updating \ | |
274 | * the operation state. \ | |
275 | * \ | |
276 | * Note that OCB1 delays output if its input is not a \ | |
277 | * whole number of blocks. This means that the output \ | |
278 | * might be smaller or larger the input by up to the block \ | |
279 | * size. \ | |
280 | */ \ | |
281 | \ | |
282 | extern int pre##_ocb1decrypt(pre##_ocb1ctx */*ctx*/, \ | |
283 | const void */*src*/, size_t /*sz*/, \ | |
284 | buf */*dst*/); \ | |
285 | \ | |
286 | /* --- @pre_ocb1encryptdone@ --- * \ | |
287 | * \ | |
288 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to an OCB1 context \ | |
289 | * @const pre_ocb1aadctx *aad@ = pointer to AAD context, \ | |
290 | * or null \ | |
291 | * @buf *dst@ = buffer for remaining ciphertext \ | |
292 | * @void *tag@ = where to write the tag \ | |
293 | * @size_t tsz@ = length of tag to store \ | |
294 | * \ | |
295 | * Returns: Zero on success; @-1@ on failure. \ | |
296 | * \ | |
297 | * Use: Completes an OCB1 encryption operation. The @aad@ \ | |
298 | * pointer may be null if there is no additional \ | |
299 | * authenticated data. OCB1 delays output, so this will \ | |
300 | * cause any remaining buffered plaintext to be encrypted \ | |
301 | * and written to @dst@. Anyway, the function will fail \ | |
302 | * if the output buffer is broken. \ | |
303 | */ \ | |
304 | \ | |
305 | extern int pre##_ocb1encryptdone(pre##_ocb1ctx */*ctx*/, \ | |
306 | const pre##_ocb1aadctx */*aad*/, \ | |
307 | buf */*dst*/, \ | |
308 | void */*tag*/, size_t /*tsz*/); \ | |
309 | \ | |
310 | /* --- @pre_ocb1decryptdone@ --- * \ | |
311 | * \ | |
312 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to an OCB1 context \ | |
313 | * @const pre_ocb1aadctx *aad@ = pointer to AAD context, \ | |
314 | * or null \ | |
315 | * @buf *dst@ = buffer for remaining plaintext \ | |
316 | * @const void *tag@ = tag to verify \ | |
317 | * @size_t tsz@ = length of tag \ | |
318 | * \ | |
319 | * Returns: @+1@ for complete success; @0@ if tag verification \ | |
320 | * failed; @-1@ for other kinds of errors. \ | |
321 | * \ | |
322 | * Use: Completes an OCB1 decryption operation. The @aad@ \ | |
323 | * pointer may be null if there is no additional \ | |
324 | * authenticated data. OCB1 delays output, so this will \ | |
325 | * cause any remaining buffered ciphertext to be decrypted \ | |
326 | * and written to @dst@. Anyway, the function will fail \ | |
327 | * if the output buffer is broken. \ | |
328 | */ \ | |
329 | \ | |
330 | extern int pre##_ocb1decryptdone(pre##_ocb1ctx */*ctx*/, \ | |
331 | const pre##_ocb1aadctx */*aad*/, \ | |
332 | buf */*dst*/, \ | |
333 | const void */*tag*/, size_t /*tsz*/); \ | |
334 | \ | |
335 | /* --- Generic AEAD interface --- */ \ | |
336 | \ | |
337 | extern const gcaead pre##_ocb1; | |
338 | ||
339 | /*----- That's all, folks -------------------------------------------------*/ | |
340 | ||
341 | #ifdef __cplusplus | |
342 | } | |
343 | #endif | |
344 | ||
345 | #endif |