Commit | Line | Data |
---|---|---|
09734e51 MW |
1 | /* -*-c-*- |
2 | * | |
3 | * The OCB3 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 OCB3 -----------------------------------------------------* | |
29 | * | |
30 | * OCB3 was designed in 2011 by Phillip Rogaway and Ted Krovetz, building ten | |
31 | * years of earlier work by Rogaway, Bellare, and Black, and refining Jutla's | |
32 | * pioneering work on IACBC and IAPM. OCB3 is an efficient `authenticated | |
33 | * encryption with associated data' (AEAD) scheme which requires only one | |
34 | * blockcipher application per message block. | |
35 | * | |
36 | * The patent situation on these efficient authenticated encryption schemes | |
37 | * is fraught. IBM hold two patents on Jutla's pioneering work on `IACBC' | |
38 | * and `IAPM' which can apply (a third was filed at least six years too | |
39 | * late), and Virgil Gligor and Pompiliu Donescu hold patents on their `XECB' | |
40 | * and `XCBC' modes; these may or may not apply to OCB. Rogaway himself | |
41 | * holds US patents on various versions of OCB, but has issued free licences | |
42 | * for free (`open source') software, and for all non-military use. I think | |
43 | * Catacomb's implementation of OCB falls within the scope of the former | |
44 | * licence. | |
45 | * | |
46 | * OCB3 has optimized for short messages with `similar' nonces, where | |
47 | * `similar' means `all but the low bits in the last byte are equal'; exactly | |
48 | * how many bits depends on the block length in a rather complicated manner. | |
49 | * This implementation supports this optimization through @pre_ocb3reinit@ | |
50 | * (which compares the new nonce against the old one to see whether it can | |
51 | * make use of the similarity), and, more directly, through @pre_ocb3step@, | |
52 | * which (effectively) advances the nonce as a big-endian counter. | |
53 | * | |
54 | * OCB3 was originally defined only for 128-bit blockciphers, and extending | |
55 | * it to other sizes is nontrivial, but this has been done by Ted Krovetz in | |
56 | * I-D draft-krovetz-ocb-wideblock-00 (following initial prompting from, err, | |
57 | * me). | |
58 | * | |
59 | * OCB3 is a fairly well-behaved AEAD mode. It doesn't require | |
60 | * precommentment to the header or message lengths, but does require | |
61 | * precommitment to the tag length. It permits header data to be processed | |
62 | * independently of any message. It only accepts nonces the same size as the | |
63 | * underlying blockcipher's block size, and it buffers up to a whole block's | |
64 | * worth of data internally, which somewhat complicates streaming. | |
65 | */ | |
66 | ||
67 | #ifndef CATACOMB_OCB3_H | |
68 | #define CATACOMB_OCB3_H | |
69 | ||
70 | #ifdef __cplusplus | |
71 | extern "C" { | |
72 | #endif | |
73 | ||
74 | /*----- Header files ------------------------------------------------------*/ | |
75 | ||
76 | #include <stddef.h> | |
77 | ||
78 | #include <mLib/bits.h> | |
79 | #include <mLib/buf.h> | |
80 | ||
81 | #ifndef CATACOMB_GAEAD_H | |
82 | # include "gaead.h" | |
83 | #endif | |
84 | ||
85 | #ifndef CATACOMB_OCB_H | |
86 | # include "ocb.h" | |
87 | #endif | |
88 | ||
89 | /*----- Macros ------------------------------------------------------------*/ | |
90 | ||
91 | /* --- @OCB3_DECL@ --- * | |
92 | * | |
93 | * Arguments: @PRE@, @pre@ = prefixes for the underlying block cipher | |
94 | * | |
95 | * Use: Creates declarations for OCB3 message-authentication mode. | |
96 | */ | |
97 | ||
98 | #define OCB3_NSZMAX(PRE) (PRE##_BLKSZ - (PRE##_BLKSZ <= 16 ? 1 : 2)) | |
99 | ||
100 | #define OCB3_DECL(PRE, pre) \ | |
101 | \ | |
102 | typedef struct pre##_ocb3key { \ | |
103 | pre##_ctx ctx; /* Underlying cipher context */ \ | |
104 | uint32 lstar[PRE##_BLKSZ/4]; /* Partial-block mask */ \ | |
105 | uint32 ldollar[PRE##_BLKSZ/4]; /* Checksum mask */ \ | |
106 | uint32 lmask[OCB_NCALC][PRE##_BLKSZ/4]; /* Precalculated masks */ \ | |
107 | } pre##_ocb3key; \ | |
108 | \ | |
109 | typedef struct pre##_ocb3aadctx { \ | |
110 | pre##_ocb3key k; /* Processed key material */ \ | |
111 | uint32 o[PRE##_BLKSZ/4]; /* Current offset */ \ | |
112 | uint32 a[PRE##_BLKSZ/4]; /* Accumulator state */ \ | |
113 | octet b[PRE##_BLKSZ]; /* Input buffer */ \ | |
114 | unsigned long i; /* Block counter */ \ | |
115 | unsigned off; /* Offset into buffered data */ \ | |
116 | } pre##_ocb3aadctx; \ | |
117 | \ | |
118 | typedef struct pre##_ocb3ctx { \ | |
119 | pre##_ocb3key k; /* Processed key material */ \ | |
120 | unsigned nix, tsz; /* Nonce index and tag size */ \ | |
121 | uint32 nbase[PRE##_BLKSZ/2]; /* Current base nonce */ \ | |
122 | uint32 nstretch[PRE##_BLKSZ/2]; /* Stretched nonce material */ \ | |
123 | uint32 o[PRE##_BLKSZ/4]; /* Current offset */ \ | |
124 | uint32 a[PRE##_BLKSZ/4]; /* Accumulator state */ \ | |
125 | octet b[PRE##_BLKSZ]; /* Input buffer */ \ | |
126 | unsigned long i; /* Block counter */ \ | |
127 | unsigned off; /* Offset into buffered data */ \ | |
128 | } pre##_ocb3ctx; \ | |
129 | \ | |
130 | extern const octet pre##_ocb3noncesz[], pre##_ocb3tagsz[]; \ | |
131 | \ | |
132 | /* --- @pre_ocb3setkey@ --- * \ | |
133 | * \ | |
134 | * Arguments: @pre_ocb3key *key@ = pointer to key block to fill in \ | |
135 | * @const void *k@ = pointer to key material \ | |
136 | * @size_t ksz@ = size of key material \ | |
137 | * \ | |
138 | * Returns: --- \ | |
139 | * \ | |
140 | * Use: Initializes an OCB3 key block. \ | |
141 | */ \ | |
142 | \ | |
143 | extern void pre##_ocb3setkey(pre##_ocb3key */*key*/, \ | |
144 | const void */*k*/, size_t /*ksz*/); \ | |
145 | \ | |
146 | /* --- @pre_ocb3aadinit@ --- * \ | |
147 | * \ | |
148 | * Arguments: @pre_ocb3aadctx *aad@ = pointer to AAD context \ | |
149 | * @const pre_ocb3key *key@ = pointer to key block \ | |
150 | * \ | |
151 | * Returns: --- \ | |
152 | * \ | |
153 | * Use: Initializes an OCB3 AAD (`additional authenticated \ | |
154 | * data') context associated with a given key. AAD \ | |
155 | * contexts can be copied and/or reused, saving time if \ | |
156 | * the AAD for number of messages has a common prefix. \ | |
157 | * \ | |
158 | * The @key@ doesn't need to be kept around, though \ | |
159 | * usually there'll at least be another copy in some OCB3 \ | |
160 | * operation context because the AAD on its own isn't much \ | |
161 | * good. \ | |
162 | */ \ | |
163 | \ | |
164 | extern void pre##_ocb3aadinit(pre##_ocb3aadctx */*aad*/, \ | |
165 | const pre##_ocb3key */*key*/); \ | |
166 | \ | |
167 | /* --- @pre_ocb3aadhash@ --- * \ | |
168 | * \ | |
169 | * Arguments: @pre_ocb3aadctx *aad@ = pointer to AAD context \ | |
170 | * @const void *p@ = pointer to AAD material \ | |
171 | * @size_t sz@ = length of AAD material \ | |
172 | * \ | |
173 | * Returns: --- \ | |
174 | * \ | |
175 | * Use: Feeds AAD into the context. \ | |
176 | */ \ | |
177 | \ | |
178 | extern void pre##_ocb3aadhash(pre##_ocb3aadctx */*aad*/, \ | |
179 | const void */*p*/, size_t /*sz*/); \ | |
180 | \ | |
181 | /* --- @pre_ocb3init@ --- * \ | |
182 | * \ | |
183 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 context \ | |
184 | * @const pre_ocb3key *key@ = pointer to key block \ | |
185 | * @const void *n@ = pointer to nonce \ | |
186 | * @size_t nsz@ = size of nonce \ | |
187 | * @size_t tsz@ = tag length \ | |
188 | * \ | |
189 | * Returns: Zero on success, @-1@ if the nonce or tag length is \ | |
190 | * bad. \ | |
191 | * \ | |
192 | * Use: Initialize an OCB3 operation context with a given key. \ | |
193 | * \ | |
194 | * The original key needn't be kept around any more. \ | |
195 | */ \ | |
196 | \ | |
197 | extern int pre##_ocb3init(pre##_ocb3ctx */*ctx*/, \ | |
198 | const pre##_ocb3key */*k*/, \ | |
199 | const void */*n*/, size_t /*nsz*/, \ | |
200 | size_t /*tsz*/); \ | |
201 | \ | |
202 | /* --- @pre_ocb3reinit@ --- * \ | |
203 | * \ | |
204 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 context \ | |
205 | * @const void *n@ = pointer to nonce \ | |
206 | * @size_t nsz@ = size of nonce \ | |
207 | * @size_t tsz@ = tag length \ | |
208 | * \ | |
209 | * Returns: Zero on success, @-1@ if the nonce or tag length is \ | |
210 | * bad. \ | |
211 | * \ | |
212 | * Use: Reinitialize an OCB3 operation context, changing the \ | |
213 | * nonce and/or tag length. \ | |
214 | */ \ | |
215 | \ | |
216 | extern int pre##_ocb3reinit(pre##_ocb3ctx */*ctx*/, \ | |
217 | const void */*n*/, size_t /*nsz*/, \ | |
218 | size_t /*tsz*/); \ | |
219 | \ | |
220 | /* --- @pre_ocb3step@ --- * \ | |
221 | * \ | |
222 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 context \ | |
223 | * \ | |
224 | * Returns: --- \ | |
225 | * \ | |
226 | * Use: Reinitialize an OCB3 operation context, stepping to \ | |
227 | * the `next' nonce along. \ | |
228 | */ \ | |
229 | \ | |
230 | extern void pre##_ocb3step(pre##_ocb3ctx */*ctx*/); \ | |
231 | \ | |
232 | /* --- @pre_ocb3encrypt@ --- * \ | |
233 | * \ | |
234 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 operation context \ | |
235 | * @const void *src@ = pointer to plaintext message chunk \ | |
236 | * @size_t sz@ = size of the plaintext \ | |
237 | * @buf *dst@ = a buffer to write the ciphertext to \ | |
238 | * \ | |
239 | * Returns: Zero on success; @-1@ on failure. \ | |
240 | * \ | |
241 | * Use: Encrypts a chunk of a plaintext message, writing a \ | |
242 | * chunk of ciphertext to the output buffer and updating \ | |
243 | * the operation state. \ | |
244 | * \ | |
245 | * Note that OCB3 delays output if its input is not a \ | |
246 | * whole number of blocks. This means that the output \ | |
247 | * might be smaller or larger the input by up to the block \ | |
248 | * size. \ | |
249 | */ \ | |
250 | \ | |
251 | extern int pre##_ocb3encrypt(pre##_ocb3ctx */*ctx*/, \ | |
252 | const void */*src*/, size_t /*sz*/, \ | |
253 | buf */*dst*/); \ | |
254 | \ | |
255 | /* --- @pre_ocb3decrypt@ --- * \ | |
256 | * \ | |
257 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 operation context \ | |
258 | * @const void *src@ = pointer to ciphertext message chunk \ | |
259 | * @size_t sz@ = size of the ciphertext \ | |
260 | * @buf *dst@ = a buffer to write the plaintext to \ | |
261 | * \ | |
262 | * Returns: Zero on success; @-1@ on failure. \ | |
263 | * \ | |
264 | * Use: Decrypts a chunk of a ciphertext message, writing a \ | |
265 | * chunk of plaintext to the output buffer and updating \ | |
266 | * the operation state. \ | |
267 | * \ | |
268 | * Note that OCB3 delays output if its input is not a \ | |
269 | * whole number of blocks. This means that the output \ | |
270 | * might be smaller or larger the input by up to the block \ | |
271 | * size. \ | |
272 | */ \ | |
273 | \ | |
274 | extern int pre##_ocb3decrypt(pre##_ocb3ctx */*ctx*/, \ | |
275 | const void */*src*/, size_t /*sz*/, \ | |
276 | buf */*dst*/); \ | |
277 | \ | |
278 | /* --- @pre_ocb3encryptdone@ --- * \ | |
279 | * \ | |
280 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to an OCB3 context \ | |
281 | * @const pre_ocb3aadctx *aad@ = pointer to AAD context, \ | |
282 | * or null \ | |
283 | * @buf *dst@ = buffer for remaining ciphertext \ | |
284 | * @void *tag@ = where to write the tag \ | |
285 | * @size_t tsz@ = length of tag to store \ | |
286 | * \ | |
287 | * Returns: Zero on success; @-1@ on failure. \ | |
288 | * \ | |
289 | * Use: Completes an OCB3 encryption operation. The @aad@ \ | |
290 | * pointer may be null if there is no additional \ | |
291 | * authenticated data. OCB3 delays output, so this will \ | |
292 | * cause any remaining buffered plaintext to be encrypted \ | |
293 | * and written to @dst@. Anyway, the function will fail \ | |
294 | * if the output buffer is broken. \ | |
295 | */ \ | |
296 | \ | |
297 | extern int pre##_ocb3encryptdone(pre##_ocb3ctx */*ctx*/, \ | |
298 | const pre##_ocb3aadctx */*aad*/, \ | |
299 | buf */*dst*/, \ | |
300 | void */*tag*/, size_t /*tsz*/); \ | |
301 | \ | |
302 | /* --- @pre_ocb3decryptdone@ --- * \ | |
303 | * \ | |
304 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to an OCB3 context \ | |
305 | * @const pre_ocb3aadctx *aad@ = pointer to AAD context, \ | |
306 | * or null \ | |
307 | * @buf *dst@ = buffer for remaining plaintext \ | |
308 | * @const void *tag@ = tag to verify \ | |
309 | * @size_t tsz@ = length of tag \ | |
310 | * \ | |
311 | * Returns: @+1@ for complete success; @0@ if tag verification \ | |
312 | * failed; @-1@ for other kinds of errors. \ | |
313 | * \ | |
314 | * Use: Completes an OCB3 decryption operation. The @aad@ \ | |
315 | * pointer may be null if there is no additional \ | |
316 | * authenticated data. OCB3 delays output, so this will \ | |
317 | * cause any remaining buffered ciphertext to be decrypted \ | |
318 | * and written to @dst@. Anyway, the function will fail \ | |
319 | * if the output buffer is broken. \ | |
320 | */ \ | |
321 | \ | |
322 | extern int pre##_ocb3decryptdone(pre##_ocb3ctx */*ctx*/, \ | |
323 | const pre##_ocb3aadctx */*aad*/, \ | |
324 | buf */*dst*/, \ | |
325 | const void */*tag*/, size_t /*tsz*/); \ | |
326 | \ | |
327 | /* --- Generic AEAD interface --- */ \ | |
328 | \ | |
329 | extern const gcaead pre##_ocb3; | |
330 | ||
331 | /*----- That's all, folks -------------------------------------------------*/ | |
332 | ||
333 | #ifdef __cplusplus | |
334 | } | |
335 | #endif | |
336 | ||
337 | #endif |