[catacomb] / symm / ocb1.h

/* -*-c-*-
 *
 * The OCB1 authenticated encryption mode
 *
 * (c) 2018 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 OCB1 -----------------------------------------------------*
 *
 * OCB was designed in 2001 by Phillip Rogaway, with Mihir Bellare and John
 * Black, as a blockcipher-based authenticated encryption scheme which can
 * operate on multiple message blocks in parallel and requires only a single
 * blockcipher application per message block.  It refines Charanjit Jutla's
 * earlier IAPM, which was the first such mode to be proven secure.  This
 * version implements the `OCB.PMAC' mode described by Rogaway in 2002, which
 * combines the original OCB with PMAC (Rogaway and Black, 2002) into a
 * single authenticated-encryption with associated-data (AEAD) scheme.
 *
 * The patent situation on these efficient authenticated encryption schemes
 * is fraught.  IBM hold two patents on Jutla's pioneering work on `IACBC'
 * and `IAPM' which can apply (a third was filed at least six years too
 * late), and Virgil Gligor and Pompiliu Donescu hold patents on their `XECB'
 * and `XCBC' modes; these may or may not apply to OCB.  Rogaway himself
 * holds US patents on various versions of OCB, but has issued free licences
 * for free (`open source') software, and for all non-military use.  I think
 * Catacomb's implementation of OCB falls within the scope of the former
 * licence.
 *
 * Confusingly, Rogaway's 2004 paper `Efficient Instantiations of Tweakable
 * Blockciphers and Refinements to Modes OCB and PMAC' named the new versions
 * of those modes `OCB1' and `PMAC1'.  The 2011 paper by Krovetz and Rogaway,
 * `The Software Performance of Authenticated-Encryption Modes' renamed the
 * original 2001 version of OCB as `OCB1', and the 2004 version `OCB2', and
 * introduced a new `OCB3'.  I've decided to follow and extend the 2011
 * naming, so `OCB1' refers to the 2001 OCB; the 2004 version would be
 * `OCB2'.
 *
 * The OCB specification is clear about how OCB applies to arbitrary block
 * sizes.
 *
 * OCB1 is a fairly well-behaved AEAD mode.  It doesn't require
 * precommentment to any lengths, and allows header data to be processed
 * independently of any message.  On the other hand, it only accepts nonces
 * the same size as the underlying blockcipher's block size, and it buffers
 * up to a whole block's worth of data internally, which somewhat complicates
 * streaming.
 */

#ifndef CATACOMB_OCB1_H
#define CATACOMB_OCB1_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

#ifndef CATACOMB_OCB_H
#  include "ocb.h"
#endif

#ifndef CATACOMB_RSVR_H
#  include "rsvr.h"
#endif

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

/* --- @OCB1_DECL@ --- *
 *
 * Arguments:	@PRE@, @pre@ = prefixes for the underlying block cipher
 *
 * Use:		Creates declarations for OCB1 message-authentication mode.
 */

#define OCB1_STRUCTS(PRE, pre, keyty, aadty)				\
									\
typedef struct keyty {							\
  pre##_ctx ctx;			/* Underlying cipher context */	\
  uint32 lxinv[PRE##_BLKSZ/4];		/* Final-block mask */		\
  uint32 lmask[OCB_NCALC][PRE##_BLKSZ/4]; /* Precalculated masks */	\
} keyty;								\
									\
typedef struct aadty {							\
  keyty k;				/* Processed key material */	\
  uint32 o[PRE##_BLKSZ/4];		/* Current offset */		\
  uint32 a[PRE##_BLKSZ/4];		/* Accumulator state */		\
  octet b[PRE##_BLKSZ];			/* Input buffer */		\
  unsigned long i;			/* Block counter */		\
  unsigned off;				/* Offset into buffered data */	\
} aadty;

#define OCB1_DECL(PRE, pre)						\
									\
OCB1_STRUCTS(PRE, pre, pre##_ocb1key, pre##_ocb1aadctx)			\
									\
typedef struct pre##_ocb1ctx {						\
  /* This is the same as @pre_ocb1aadctx@ above, but the two are	\
   * logically distinct and shouldn't be muddled up.			\
   */									\
									\
  pre##_ocb1key k;			/* Processed key material */	\
  uint32 o[PRE##_BLKSZ/4];		/* Current offset */		\
  uint32 a[PRE##_BLKSZ/4];		/* Accumulator state */		\
  octet b[PRE##_BLKSZ];			/* Input buffer */		\
  unsigned long i;			/* Block counter */		\
  unsigned off;				/* Offset into buffered data */	\
} pre##_ocb1ctx;							\
									\
extern const rsvr_policy pre##_ocb1policy;				\
									\
extern const octet pre##_ocb1noncesz[], pre##_ocb1tagsz[];		\
									\
/* --- @pre_ocb1setkey@ --- *						\
 *									\
 * Arguments:	@pre_ocb1key *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 OCB1 key block.				\
 */									\
									\
extern void pre##_ocb1setkey(pre##_ocb1key */*key*/,			\
			     const void */*k*/, size_t /*ksz*/);	\
									\
/* --- @pre_ocb1aadinit@ --- *						\
 *									\
 * Arguments:	@pre_ocb1aadctx *aad@ = pointer to AAD context		\
 *		@const pre_ocb1key *key@ = pointer to key block		\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Initializes an OCB1 AAD (`additional authenticated	\
 *		data') context associated with a given key.  AAD	\
 *		contexts can be copied and/or reused, saving time if	\
 *		the AAD for 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 OCB1	\
 *		operation context because the AAD on its own isn't much	\
 *		good.							\
 */									\
									\
extern void pre##_ocb1aadinit(pre##_ocb1aadctx */*aad*/,		\
			      const pre##_ocb1key */*key*/);		\
									\
/* --- @pre_ocb1aadhash@ --- *						\
 *									\
 * Arguments:	@pre_ocb1aadctx *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##_ocb1aadhash(pre##_ocb1aadctx */*aad*/,		\
			      const void */*p*/, size_t /*sz*/);	\
									\
/* --- @pre_ocb1aadtag@ --- *						\
 *									\
 * Arguments:	@const pre_ocb1aadctx *aad@ = pointer to context block	\
 *		@uint32 *u@ = where to write the tag			\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Finishes processing AAD and produces a tag which can be	\
 *		mixed with an OCB1 checksum.  This function is exposed	\
 *		for internal reasons and is not expected to be		\
 *		generally useful.					\
 */									\
									\
extern void pre##_ocb1aadtag(const pre##_ocb1aadctx */*aad*/,		\
			     uint32 */*t*/);				\
									\
/* --- @pre_ocb1init@ --- *						\
 *									\
 * Arguments:	@pre_ocb1ctx *ctx@ = pointer to OCB1 context		\
 *		@const pre_ocb1key *key@ = pointer to key block		\
 *		@const void *n@ = pointer to nonce			\
 *		@size_t nsz@ = size of nonce				\
 *									\
 * Returns:	Zero on success, @-1@ if the nonce length is bad.	\
 *									\
 * Use:		Initialize an OCB1 operation context with a given key.	\
 *									\
 *		The original key needn't be kept around any more.	\
 */									\
									\
extern int pre##_ocb1init(pre##_ocb1ctx */*ctx*/,			\
			  const pre##_ocb1key */*k*/,			\
			  const void */*n*/, size_t /*nsz*/);		\
									\
/* --- @pre_ocb1reinit@ --- *						\
 *									\
 * Arguments:	@pre_ocb1ctx *ctx@ = pointer to OCB1 context		\
 *		@const void *n@ = pointer to nonce			\
 *		@size_t nsz@ = size of nonce				\
 *									\
 * Returns:	Zero on success, @-1@ if the nonce length is bad.	\
 *									\
 * Use:		Reinitialize an OCB1 operation context, changing the	\
 *		nonce.							\
 */									\
									\
extern int pre##_ocb1reinit(pre##_ocb1ctx */*ctx*/,			\
			    const void */*n*/, size_t /*nsz*/);		\
									\
/* --- @pre_ocb1encrypt@ --- *						\
 *									\
 * Arguments:	@pre_ocb1ctx *ctx@ = pointer to OCB1 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.					\
 *									\
 *		Note that OCB1 delays output if its input is not a	\
 *		whole number of blocks.  This means that the output	\
 *		might be smaller or larger the input by up to the block	\
 *		size.							\
 */									\
									\
extern int pre##_ocb1encrypt(pre##_ocb1ctx */*ctx*/,			\
			     const void */*src*/, size_t /*sz*/,	\
			     buf */*dst*/);				\
									\
/* --- @pre_ocb1decrypt@ --- *						\
 *									\
 * Arguments:	@pre_ocb1ctx *ctx@ = pointer to OCB1 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.					\
 *									\
 *		Note that OCB1 delays output if its input is not a	\
 *		whole number of blocks.  This means that the output	\
 *		might be smaller or larger the input by up to the block	\
 *		size.							\
 */									\
									\
extern int pre##_ocb1decrypt(pre##_ocb1ctx */*ctx*/,			\
			     const void */*src*/, size_t /*sz*/,	\
			     buf */*dst*/);				\
									\
/* --- @pre_ocb1encryptdone@ --- *					\
 *									\
 * Arguments:	@pre_ocb1ctx *ctx@ = pointer to an OCB1 context		\
 *		@const pre_ocb1aadctx *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 OCB1 encryption operation.  The @aad@	\
 *		pointer may be null if there is no additional		\
 *		authenticated data.  OCB1 delays output, so this will	\
 *		cause any remaining buffered plaintext to be encrypted	\
 *		and written to @dst@.  Anyway, the function will fail	\
 *		if the output buffer is broken.				\
 */									\
									\
extern int pre##_ocb1encryptdone(pre##_ocb1ctx */*ctx*/,		\
				 const pre##_ocb1aadctx */*aad*/,	\
				 buf */*dst*/,				\
				 void */*tag*/, size_t /*tsz*/);	\
									\
/* --- @pre_ocb1decryptdone@ --- *					\
 *									\
 * Arguments:	@pre_ocb1ctx *ctx@ = pointer to an OCB1 context		\
 *		@const pre_ocb1aadctx *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 OCB1 decryption operation.  The @aad@	\
 *		pointer may be null if there is no additional		\
 *		authenticated data.  OCB1 delays output, so this will	\
 *		cause any remaining buffered ciphertext to be decrypted	\
 *		and written to @dst@.  Anyway, the function will fail	\
 *		if the output buffer is broken.				\
 */									\
									\
extern int pre##_ocb1decryptdone(pre##_ocb1ctx */*ctx*/,		\
				 const pre##_ocb1aadctx */*aad*/,	\
				 buf */*dst*/,				\
				 const void */*tag*/, size_t /*tsz*/);	\
									\
/* --- Generic AEAD interface --- */					\
									\
extern const gcaead pre##_ocb1;

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

#ifdef __cplusplus
  }
#endif

#endif
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