[catacomb] / symm / eax.h

/* -*-c-*-
 *
 * The EAX authenticated-encryption mode
 *
 * (c) 2017 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * Catacomb is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Notes on EAX ------------------------------------------------------*
 *
 * The name doesn't appear to be short for anything convincing.  EAX was
 * designed in 2004 by Mihir Bellare, Phillip Rogaway, and David Wagner, as a
 * response to CCM's deficiencies, which Rogaway and Wagner had complained
 * about the previous year.  Like CCM, it's a patent-free authenticated
 * encryption scheme based on counter mode and CBC-MAC, and needs two
 * blockcipher applications per message block, but it's much more refined
 * than CCM.  The EAX specification is clear about how the mode applies to
 * arbitrary block sizes, and I've not had to make any decisions on how to
 * extend it myself.
 *
 * EAX allows arbitrarily sized nonces, and doesn't require precommitment to
 * any lengths, and allows header data to be processed independently of any
 * message.  It's basically about as good as a rate-1/2 scheme is going to
 * be.
 */

#ifndef CATACOMB_EAX_H
#define CATACOMB_EAX_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <stddef.h>

#include <mLib/bits.h>
#include <mLib/buf.h>

#ifndef CATACOMB_GAEAD_H
#  include "gaead.h"
#endif

/*----- Macros ------------------------------------------------------------*/

/* --- @EAX_DECL@ --- *
 *
 * Arguments:	@PRE@, @pre@ = prefixes for the underlying block cipher
 *
 * Use:		Creates declarations for EAX authenticated-encryption mode.
 */

#define EAX_DECL(PRE, pre)						\
									\
typedef struct pre##_eaxkey {						\
  pre##_ctx ctx;			/* Block cipher key */		\
  uint32 m0[PRE##_BLKSZ/4], m1[PRE##_BLKSZ/4]; /* Final OMAC masks */	\
  uint32 v0[PRE##_BLKSZ/4],		/* OMAC tweak accumulators */	\
    v1[PRE##_BLKSZ/4], v2[PRE##_BLKSZ/4];				\
  uint32 z0[PRE##_BLKSZ/4],		/* Empty-message tag values */	\
    z1[PRE##_BLKSZ/4], z2[PRE##_BLKSZ/4];				\
} pre##_eaxkey;								\
									\
typedef struct pre##_eaxaadctx {					\
  pre##_eaxkey k;			/* Underlying key */		\
  uint32 a[PRE##_BLKSZ/4];		/* OMAC accumulator */		\
  octet b[PRE##_BLKSZ];			/* Input buffer */		\
  unsigned off;				/* Length of stuff in buffer */	\
} pre##_eaxaadctx;							\
									\
typedef struct pre##_eaxctx {						\
  /* The buffer is split into two portions.  The first N octets hold a	\
   * chunk of ciphertext, which will be fed into the OMAC calculation;	\
   * the remaining BLKSZ - N octets hold E_K(C), which is the XOR mask	\
   * to apply to the plaintext or ciphertext.				\
   */									\
  pre##_eaxkey k;			/* Underlying key */		\
  uint32 c[PRE##_BLKSZ/4];		/* Current counter value */	\
  uint32 c0[PRE##_BLKSZ/4];		/* Initial counter */		\
  uint32 a[PRE##_BLKSZ];		/* OMAC accumulator */		\
  octet b[PRE##_BLKSZ];			/* Ciphertext/mask buffer */	\
  unsigned off;				/* Crossover point in buffer */	\
} pre##_eaxctx;								\
									\
extern const octet pre##_eaxnoncesz[], pre##_eaxtagsz[];		\
									\
/* --- @pre_eaxsetkey@ --- *						\
 *									\
 * Arguments:	@pre_eaxkey *key@ = pointer to key block to fill in	\
 *		@const void *k@ = pointer to key material		\
 *		@size_t ksz@ = size of key material			\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Initializes an EAX key block.				\
 */									\
									\
extern void pre##_eaxsetkey(pre##_eaxkey */*key*/,			\
			    const void */*k*/, size_t /*ksz*/);		\
									\
/* --- @pre_eaxaadinit@ --- *						\
 *									\
 * Arguments:	@pre_eaxaadctx *aad@ = pointer to AAD context		\
 *		@const pre_eaxkey *key@ = pointer to key block		\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Initializes an EAX AAD (`additional authenticated	\
 *		data') context associated with a given key.  AAD	\
 *		contexts can be copied and/or reused, saving time if	\
 *		the AAD for a number of messages has a common prefix.	\
 *									\
 *		The @key@ doesn't need to be kept around, though	\
 *		usually there'll at least be another copy in some EAX	\
 *		operation context because the AAD on its own isn't much	\
 *		good.							\
 */									\
									\
extern void pre##_eaxaadinit(pre##_eaxaadctx */*aad*/,			\
			     const pre##_eaxkey */*key*/);		\
									\
/* --- @pre_eaxaadhash@ --- *						\
 *									\
 * Arguments:	@pre_eaxaadctx *aad@ = pointer to AAD context		\
 *		@const void *p@ = pointer to AAD material		\
 *		@size_t sz@ = length of AAD material			\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Feeds AAD into the context.				\
 */									\
									\
extern void pre##_eaxaadhash(pre##_eaxaadctx */*aad*/,			\
			     const void */*p*/, size_t /*sz*/);		\
									\
/* --- @pre_eaxinit@ --- *						\
 *									\
 * Arguments:	@pre_eaxctx *ctx@ = pointer to EAX context		\
 *		@const pre_eaxkey *key@ = pointer to key block		\
 *		@const void *n@ = pointer to nonce			\
 *		@size_t nsz@ = size of nonce				\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Initialize an EAX operation context with a given key.	\
 *									\
 *		The original key needn't be kept around any more.	\
 */									\
									\
extern void pre##_eaxinit(pre##_eaxctx */*ctx*/,			\
			  const pre##_eaxkey */*k*/,			\
			  const void */*n*/, size_t /*nsz*/);		\
									\
/* --- @pre_eaxreinit@ --- *						\
 *									\
 * Arguments:	@pre_eaxctx *ctx@ = pointer to EAX context		\
 *		@const void *n@ = pointer to nonce			\
 *		@size_t nsz@ = size of nonce				\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Reinitialize an EAX operation context, changing the	\
 *		nonce.							\
 */									\
									\
extern void pre##_eaxreinit(pre##_eaxctx */*ctx*/,			\
			    const void */*n*/, size_t /*nsz*/);		\
									\
/* --- @pre_eaxencrypt@ --- *						\
 *									\
 * Arguments:	@pre_eaxctx *ctx@ = pointer to EAX operation context	\
 *		@const void *src@ = pointer to plaintext message chunk	\
 *		@size_t sz@ = size of the plaintext			\
 *		@buf *dst@ = a buffer to write the ciphertext to	\
 *									\
 * Returns:	Zero on success; @-1@ on failure.			\
 *									\
 * Use:		Encrypts a chunk of a plaintext message, writing a	\
 *		chunk of ciphertext to the output buffer and updating	\
 *		the operation state.					\
 *									\
 *		For EAX, we always write a ciphertext chunk the same	\
 *		size as the plaintext.  The messing about with @buf@	\
 *		objects makes the interface consistent with other AEAD	\
 *		schemes which can't do this.				\
 */									\
									\
extern int pre##_eaxencrypt(pre##_eaxctx */*ctx*/,			\
			    const void */*src*/, size_t /*sz*/,		\
			    buf */*dst*/);				\
									\
/* --- @pre_eaxdecrypt@ --- *						\
 *									\
 * Arguments:	@pre_eaxctx *ctx@ = pointer to EAX operation context	\
 *		@const void *src@ = pointer to ciphertext message chunk	\
 *		@size_t sz@ = size of the ciphertext			\
 *		@buf *dst@ = a buffer to write the plaintext to		\
 *									\
 * Returns:	Zero on success; @-1@ on failure.			\
 *									\
 * Use:		Decrypts a chunk of a ciphertext message, writing a	\
 *		chunk of plaintext to the output buffer and updating	\
 *		the operation state.					\
 *									\
 *		For EAX, we always write a plaintext chunk the same	\
 *		size as the ciphertext.  The messing about with @buf@	\
 *		objects makes the interface consistent with other AEAD	\
 *		schemes which can't do this.				\
 */									\
									\
extern int pre##_eaxdecrypt(pre##_eaxctx */*ctx*/,			\
			    const void */*src*/, size_t /*sz*/,		\
			    buf */*dst*/);				\
									\
/* --- @pre_eaxencryptdone@ --- *					\
 *									\
 * Arguments:	@pre_eaxctx *ctx@ = pointer to an EAX context		\
 *		@const pre_eaxaadctx *aad@ = pointer to AAD context, or	\
 *			null						\
 *		@buf *dst@ = buffer for remaining ciphertext		\
 *		@void *tag@ = where to write the tag			\
 *		@size_t tsz@ = length of tag to store			\
 *									\
 * Returns:	Zero on success; @-1@ on failure.			\
 *									\
 * Use:		Completes an EAX encryption operation.  The @aad@	\
 *		pointer may be null if there is no additional		\
 *		authenticated data.  EAX doesn't buffer ciphertext, but	\
 *		the output buffer is provided anyway for consistency	\
 *		with other AEAD schemes which don't have this property;	\
 *		the function will fail if the output buffer is broken.	\
 */									\
									\
extern int pre##_eaxencryptdone(pre##_eaxctx */*ctx*/,			\
				const pre##_eaxaadctx */*aad*/,		\
				buf */*dst*/,				\
				void */*tag*/, size_t /*tsz*/);		\
									\
/* --- @pre_eaxdecryptdone@ --- *					\
 *									\
 * Arguments:	@pre_eaxctx *ctx@ = pointer to an EAX context		\
 *		@const pre_eaxaadctx *aad@ = pointer to AAD context, or	\
 *			null						\
 *		@buf *dst@ = buffer for remaining plaintext		\
 *		@const void *tag@ = tag to verify			\
 *		@size_t tsz@ = length of tag				\
 *									\
 * Returns:	@+1@ for complete success; @0@ if tag verification	\
 *		failed; @-1@ for other kinds of errors.			\
 *									\
 * Use:		Completes an EAX decryption operation.  The @aad@	\
 *		pointer may be null if there is no additional		\
 *		authenticated data.  EAX doesn't buffer plaintext, but	\
 *		the output buffer is provided anyway for consistency	\
 *		with other AEAD schemes which don't have this property;	\
 *		the function will fail if the output buffer is broken.	\
 */									\
									\
extern int pre##_eaxdecryptdone(pre##_eaxctx */*ctx*/,			\
				const pre##_eaxaadctx */*aad*/,		\
				buf */*dst*/,				\
				const void */*tag*/, size_t /*tsz*/);	\
									\
/* --- Generic AEAD interface --- */					\
									\
extern const gcaead pre##_eax;

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif
Commit	Line	Data
2964c388 MW	1	/* --c--
	2	*
	3	* The EAX authenticated-encryption mode
	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 EAX ------------------------------------------------------
	29	*
	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
	38	* extend it myself.
	39	*
	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
	43	* be.
	44	*/
	45
	46	#ifndef CATACOMB_EAX_H
	47	#define CATACOMB_EAX_H
	48
	49	#ifdef __cplusplus
	50	extern "C" {
	51	#endif
	52
	53	/----- Header files ------------------------------------------------------/
	54
	55	#include <stddef.h>
	56
	57	#include <mLib/bits.h>
	58	#include <mLib/buf.h>
	59
	60	#ifndef CATACOMB_GAEAD_H
	61	# include "gaead.h"
	62	#endif
	63
	64	/----- Macros ------------------------------------------------------------/
65
66	/* --- @EAX_DECL@ --- *
67	*
68	* Arguments: @PRE@, @pre@ = prefixes for the underlying block cipher
69	*
70	* Use: Creates declarations for EAX authenticated-encryption mode.
71	*/
72
73	#define EAX_DECL(PRE, pre) \
74	\
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]; \
82	} pre##_eaxkey; \
83	\
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 */ \
89	} pre##_eaxaadctx; \
90	\
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. \
96	*/ \
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 */ \
103	} pre##_eaxctx; \
104	\
105	extern const octet pre##_eaxnoncesz[], pre##_eaxtagsz[]; \
106	\
107	/* --- @pre_eaxsetkey@ --- * \
108	* \
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 \
112	* \
113	* Returns: --- \
114	* \
115	* Use: Initializes an EAX key block. \
116	*/ \
117	\
118	extern void pre##_eaxsetkey(pre##_eaxkey /key*/, \
119	const void /k/, size_t /ksz*/); \
120	\
121	/* --- @pre_eaxaadinit@ --- * \
122	* \
123	* Arguments: @pre_eaxaadctx *aad@ = pointer to AAD context \
124	* @const pre_eaxkey *key@ = pointer to key block \
125	* \
126	* Returns: --- \
127	* \
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. \
132	* \
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 \
136	* good. \
137	*/ \
138	\
139	extern void pre##_eaxaadinit(pre##_eaxaadctx /aad*/, \
140	const pre##_eaxkey /key*/); \
141	\
142	/* --- @pre_eaxaadhash@ --- * \
143	* \
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 \
147	* \
148	* Returns: --- \
149	* \
150	* Use: Feeds AAD into the context. \
151	*/ \
152	\
153	extern void pre##_eaxaadhash(pre##_eaxaadctx /aad*/, \
154	const void /p/, size_t /sz*/); \
155	\
156	/* --- @pre_eaxinit@ --- * \
157	* \
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 \
162	* \
163	* Returns: --- \
164	* \
165	* Use: Initialize an EAX operation context with a given key. \
166	* \
167	* The original key needn't be kept around any more. \
168	*/ \
169	\
170	extern void pre##_eaxinit(pre##_eaxctx /ctx*/, \
171	const pre##_eaxkey /k*/, \
172	const void /n/, size_t /nsz*/); \
173	\
174	/* --- @pre_eaxreinit@ --- * \
175	* \
176	* Arguments: @pre_eaxctx *ctx@ = pointer to EAX context \
177	* @const void *n@ = pointer to nonce \
178	* @size_t nsz@ = size of nonce \
179	* \
180	* Returns: --- \
181	* \
182	* Use: Reinitialize an EAX operation context, changing the \
183	* nonce. \
184	*/ \
185	\
186	extern void pre##_eaxreinit(pre##_eaxctx /ctx*/, \
187	const void /n/, size_t /nsz*/); \
188	\
189	/* --- @pre_eaxencrypt@ --- * \
190	* \
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 \
195	* \
196	* Returns: Zero on success; @-1@ on failure. \
197	* \
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. \
201	* \
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. \
206	*/ \
207	\
208	extern int pre##_eaxencrypt(pre##_eaxctx /ctx*/, \
209	const void /src/, size_t /sz*/, \
210	buf /dst*/); \
211	\
212	/* --- @pre_eaxdecrypt@ --- * \
213	* \
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 \
218	* \
219	* Returns: Zero on success; @-1@ on failure. \
220	* \
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. \
224	* \
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. \
229	*/ \
230	\
231	extern int pre##_eaxdecrypt(pre##_eaxctx /ctx*/, \
232	const void /src/, size_t /sz*/, \
233	buf /dst*/); \
234	\
235	/* --- @pre_eaxencryptdone@ --- * \
236	* \
237	* Arguments: @pre_eaxctx *ctx@ = pointer to an EAX context \
238	* @const pre_eaxaadctx *aad@ = pointer to AAD context, or \
239	* null \
240	* @buf *dst@ = buffer for remaining ciphertext \
241	* @void *tag@ = where to write the tag \
242	* @size_t tsz@ = length of tag to store \
243	* \
244	* Returns: Zero on success; @-1@ on failure. \
245	* \
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. \
252	*/ \
253	\
254	extern int pre##_eaxencryptdone(pre##_eaxctx /ctx*/, \
255	const pre##_eaxaadctx /aad*/, \
256	buf /dst*/, \
257	void /tag/, size_t /tsz*/); \
258	\
259	/* --- @pre_eaxdecryptdone@ --- * \
260	* \
261	* Arguments: @pre_eaxctx *ctx@ = pointer to an EAX context \
262	* @const pre_eaxaadctx *aad@ = pointer to AAD context, or \
263	* null \
264	* @buf *dst@ = buffer for remaining plaintext \
265	* @const void *tag@ = tag to verify \
266	* @size_t tsz@ = length of tag \
267	* \
268	* Returns: @+1@ for complete success; @0@ if tag verification \
269	* failed; @-1@ for other kinds of errors. \
270	* \
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. \
277	*/ \
278	\
279	extern int pre##_eaxdecryptdone(pre##_eaxctx /ctx*/, \
280	const pre##_eaxaadctx /aad*/, \
281	buf /dst*/, \
282	const void /tag/, size_t /tsz*/); \
283	\
284	/* --- Generic AEAD interface --- */ \
285	\
286	extern const gcaead pre##_eax;
287
288	/----- That's all, folks -------------------------------------------------/
289
290	#ifdef __cplusplus
291	}
292	#endif
293
294	#endif