3 * The EAX authenticated-encryption mode
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 EAX ------------------------------------------------------*
30 * The name doesn't appear to be short for anything convincing. EAX was
31 * designed in 2004 by Mihir Bellare, Phillip Rogaway, and David Wagner, as a
32 * response to CCM's deficiencies, which Rogaway and Wagner had complained
33 * about the previous year. Like CCM, it's a patent-free authenticated
34 * encryption scheme based on counter mode and CBC-MAC, and needs two
35 * blockcipher applications per message block, but it's much more refined
36 * than CCM. The EAX specification is clear about how the mode applies to
37 * arbitrary block sizes, and I've not had to make any decisions on how to
40 * EAX allows arbitrarily sized nonces, and doesn't require precommitment to
41 * any lengths, and allows header data to be processed independently of any
42 * message. It's basically about as good as a rate-1/2 scheme is going to
46 #ifndef CATACOMB_EAX_H
47 #define CATACOMB_EAX_H
53 /*----- Header files ------------------------------------------------------*/
57 #include <mLib/bits.h>
60 #ifndef CATACOMB_GAEAD_H
64 /*----- Macros ------------------------------------------------------------*/
66 /* --- @EAX_DECL@ --- *
68 * Arguments: @PRE@, @pre@ = prefixes for the underlying block cipher
70 * Use: Creates declarations for EAX authenticated-encryption mode.
73 #define EAX_DECL(PRE, pre) \
75 typedef struct pre##_eaxkey { \
76 pre##_ctx ctx; /* Block cipher key */ \
77 uint32 m0[PRE##_BLKSZ/4], m1[PRE##_BLKSZ/4]; /* Final OMAC masks */ \
78 uint32 v0[PRE##_BLKSZ/4], /* OMAC tweak accumulators */ \
79 v1[PRE##_BLKSZ/4], v2[PRE##_BLKSZ/4]; \
80 uint32 z0[PRE##_BLKSZ/4], /* Empty-message tag values */ \
81 z1[PRE##_BLKSZ/4], z2[PRE##_BLKSZ/4]; \
84 typedef struct pre##_eaxaadctx { \
85 pre##_eaxkey k; /* Underlying key */ \
86 uint32 a[PRE##_BLKSZ/4]; /* OMAC accumulator */ \
87 octet b[PRE##_BLKSZ]; /* Input buffer */ \
88 unsigned off; /* Length of stuff in buffer */ \
91 typedef struct pre##_eaxctx { \
92 /* The buffer is split into two portions. The first N octets hold a \
93 * chunk of ciphertext, which will be fed into the OMAC calculation; \
94 * the remaining BLKSZ - N octets hold E_K(C), which is the XOR mask \
95 * to apply to the plaintext or ciphertext. \
97 pre##_eaxkey k; /* Underlying key */ \
98 uint32 c[PRE##_BLKSZ/4]; /* Current counter value */ \
99 uint32 c0[PRE##_BLKSZ/4]; /* Initial counter */ \
100 uint32 a[PRE##_BLKSZ]; /* OMAC accumulator */ \
101 octet b[PRE##_BLKSZ]; /* Ciphertext/mask buffer */ \
102 unsigned off; /* Crossover point in buffer */ \
105 extern const octet pre##_eaxnoncesz[], pre##_eaxtagsz[]; \
107 /* --- @pre_eaxsetkey@ --- * \
109 * Arguments: @pre_eaxkey *key@ = pointer to key block to fill in \
110 * @const void *k@ = pointer to key material \
111 * @size_t ksz@ = size of key material \
115 * Use: Initializes an EAX key block. \
118 extern void pre##_eaxsetkey(pre##_eaxkey */*key*/, \
119 const void */*k*/, size_t /*ksz*/); \
121 /* --- @pre_eaxaadinit@ --- * \
123 * Arguments: @pre_eaxaadctx *aad@ = pointer to AAD context \
124 * @const pre_eaxkey *key@ = pointer to key block \
128 * Use: Initializes an EAX AAD (`additional authenticated \
129 * data') context associated with a given key. AAD \
130 * contexts can be copied and/or reused, saving time if \
131 * the AAD for a number of messages has a common prefix. \
133 * The @key@ doesn't need to be kept around, though \
134 * usually there'll at least be another copy in some EAX \
135 * operation context because the AAD on its own isn't much \
139 extern void pre##_eaxaadinit(pre##_eaxaadctx */*aad*/, \
140 const pre##_eaxkey */*key*/); \
142 /* --- @pre_eaxaadhash@ --- * \
144 * Arguments: @pre_eaxaadctx *aad@ = pointer to AAD context \
145 * @const void *p@ = pointer to AAD material \
146 * @size_t sz@ = length of AAD material \
150 * Use: Feeds AAD into the context. \
153 extern void pre##_eaxaadhash(pre##_eaxaadctx */*aad*/, \
154 const void */*p*/, size_t /*sz*/); \
156 /* --- @pre_eaxinit@ --- * \
158 * Arguments: @pre_eaxctx *ctx@ = pointer to EAX context \
159 * @const pre_eaxkey *key@ = pointer to key block \
160 * @const void *n@ = pointer to nonce \
161 * @size_t nsz@ = size of nonce \
165 * Use: Initialize an EAX operation context with a given key. \
167 * The original key needn't be kept around any more. \
170 extern void pre##_eaxinit(pre##_eaxctx */*ctx*/, \
171 const pre##_eaxkey */*k*/, \
172 const void */*n*/, size_t /*nsz*/); \
174 /* --- @pre_eaxreinit@ --- * \
176 * Arguments: @pre_eaxctx *ctx@ = pointer to EAX context \
177 * @const void *n@ = pointer to nonce \
178 * @size_t nsz@ = size of nonce \
182 * Use: Reinitialize an EAX operation context, changing the \
186 extern void pre##_eaxreinit(pre##_eaxctx */*ctx*/, \
187 const void */*n*/, size_t /*nsz*/); \
189 /* --- @pre_eaxencrypt@ --- * \
191 * Arguments: @pre_eaxctx *ctx@ = pointer to EAX operation context \
192 * @const void *src@ = pointer to plaintext message chunk \
193 * @size_t sz@ = size of the plaintext \
194 * @buf *dst@ = a buffer to write the ciphertext to \
196 * Returns: Zero on success; @-1@ on failure. \
198 * Use: Encrypts a chunk of a plaintext message, writing a \
199 * chunk of ciphertext to the output buffer and updating \
200 * the operation state. \
202 * For EAX, we always write a ciphertext chunk the same \
203 * size as the plaintext. The messing about with @buf@ \
204 * objects makes the interface consistent with other AEAD \
205 * schemes which can't do this. \
208 extern int pre##_eaxencrypt(pre##_eaxctx */*ctx*/, \
209 const void */*src*/, size_t /*sz*/, \
212 /* --- @pre_eaxdecrypt@ --- * \
214 * Arguments: @pre_eaxctx *ctx@ = pointer to EAX operation context \
215 * @const void *src@ = pointer to ciphertext message chunk \
216 * @size_t sz@ = size of the ciphertext \
217 * @buf *dst@ = a buffer to write the plaintext to \
219 * Returns: Zero on success; @-1@ on failure. \
221 * Use: Decrypts a chunk of a ciphertext message, writing a \
222 * chunk of plaintext to the output buffer and updating \
223 * the operation state. \
225 * For EAX, we always write a plaintext chunk the same \
226 * size as the ciphertext. The messing about with @buf@ \
227 * objects makes the interface consistent with other AEAD \
228 * schemes which can't do this. \
231 extern int pre##_eaxdecrypt(pre##_eaxctx */*ctx*/, \
232 const void */*src*/, size_t /*sz*/, \
235 /* --- @pre_eaxencryptdone@ --- * \
237 * Arguments: @pre_eaxctx *ctx@ = pointer to an EAX context \
238 * @const pre_eaxaadctx *aad@ = pointer to AAD context, or \
240 * @buf *dst@ = buffer for remaining ciphertext \
241 * @void *tag@ = where to write the tag \
242 * @size_t tsz@ = length of tag to store \
244 * Returns: Zero on success; @-1@ on failure. \
246 * Use: Completes an EAX encryption operation. The @aad@ \
247 * pointer may be null if there is no additional \
248 * authenticated data. EAX doesn't buffer ciphertext, but \
249 * the output buffer is provided anyway for consistency \
250 * with other AEAD schemes which don't have this property; \
251 * the function will fail if the output buffer is broken. \
254 extern int pre##_eaxencryptdone(pre##_eaxctx */*ctx*/, \
255 const pre##_eaxaadctx */*aad*/, \
257 void */*tag*/, size_t /*tsz*/); \
259 /* --- @pre_eaxdecryptdone@ --- * \
261 * Arguments: @pre_eaxctx *ctx@ = pointer to an EAX context \
262 * @const pre_eaxaadctx *aad@ = pointer to AAD context, or \
264 * @buf *dst@ = buffer for remaining plaintext \
265 * @const void *tag@ = tag to verify \
266 * @size_t tsz@ = length of tag \
268 * Returns: @+1@ for complete success; @0@ if tag verification \
269 * failed; @-1@ for other kinds of errors. \
271 * Use: Completes an EAX decryption operation. The @aad@ \
272 * pointer may be null if there is no additional \
273 * authenticated data. EAX doesn't buffer plaintext, but \
274 * the output buffer is provided anyway for consistency \
275 * with other AEAD schemes which don't have this property; \
276 * the function will fail if the output buffer is broken. \
279 extern int pre##_eaxdecryptdone(pre##_eaxctx */*ctx*/, \
280 const pre##_eaxaadctx */*aad*/, \
282 const void */*tag*/, size_t /*tsz*/); \
284 /* --- Generic AEAD interface --- */ \
286 extern const gcaead pre##_eax;
288 /*----- That's all, folks -------------------------------------------------*/