[catacomb] / symm / ocb3.h

/* -*-c-*-
 *
 * The OCB3 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 OCB3 -----------------------------------------------------*
 *
 * OCB3 was designed in 2011 by Phillip Rogaway and Ted Krovetz, building ten
 * years of earlier work by Rogaway, Bellare, and Black, and refining Jutla's
 * pioneering work on IACBC and IAPM.  OCB3 is an efficient `authenticated
 * encryption with associated data' (AEAD) scheme which requires only one
 * blockcipher application per message block.
 *
 * 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.
 *
 * OCB3 has optimized for short messages with `similar' nonces, where
 * `similar' means `all but the low bits in the last byte are equal'; exactly
 * how many bits depends on the block length in a rather complicated manner.
 * This implementation supports this optimization through @pre_ocb3reinit@
 * (which compares the new nonce against the old one to see whether it can
 * make use of the similarity), and, more directly, through @pre_ocb3step@,
 * which (effectively) advances the nonce as a big-endian counter.
 *
 * OCB3 was originally defined only for 128-bit blockciphers, and extending
 * it to other sizes is nontrivial, but this has been done by Ted Krovetz in
 * I-D draft-krovetz-ocb-wideblock-00 (following initial prompting from, err,
 * me).
 *
 * OCB3 is a fairly well-behaved AEAD mode.  It doesn't require
 * precommentment to the header or message lengths, but does require
 * precommitment to the tag length.  It permits header data to be processed
 * independently of any message.  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_OCB3_H
#define CATACOMB_OCB3_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

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

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

#define OCB3_NSZMAX(PRE) (PRE##_BLKSZ - (PRE##_BLKSZ <= 16 ? 1 : 2))

#define OCB3_DECL(PRE, pre)						\
									\
typedef struct pre##_ocb3key {						\
  pre##_ctx ctx;			/* Underlying cipher context */	\
  uint32 lstar[PRE##_BLKSZ/4];		/* Partial-block mask */	\
  uint32 ldollar[PRE##_BLKSZ/4];	/* Checksum mask */		\
  uint32 lmask[OCB_NCALC][PRE##_BLKSZ/4]; /* Precalculated masks */	\
} pre##_ocb3key;							\
									\
typedef struct pre##_ocb3aadctx {					\
  pre##_ocb3key 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##_ocb3aadctx;							\
									\
typedef struct pre##_ocb3ctx {						\
  pre##_ocb3key k;			/* Processed key material */	\
  unsigned nix, tsz;			/* Nonce index and tag size */	\
  uint32 nbase[PRE##_BLKSZ/2];		/* Current base nonce */	\
  uint32 nstretch[PRE##_BLKSZ/2];	/* Stretched nonce 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##_ocb3ctx;							\
									\
extern const octet pre##_ocb3noncesz[], pre##_ocb3tagsz[];		\
									\
/* --- @pre_ocb3setkey@ --- *						\
 *									\
 * Arguments:	@pre_ocb3key *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 OCB3 key block.				\
 */									\
									\
extern void pre##_ocb3setkey(pre##_ocb3key */*key*/,			\
			     const void */*k*/, size_t /*ksz*/);	\
									\
/* --- @pre_ocb3aadinit@ --- *						\
 *									\
 * Arguments:	@pre_ocb3aadctx *aad@ = pointer to AAD context		\
 *		@const pre_ocb3key *key@ = pointer to key block		\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Initializes an OCB3 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 OCB3	\
 *		operation context because the AAD on its own isn't much	\
 *		good.							\
 */									\
									\
extern void pre##_ocb3aadinit(pre##_ocb3aadctx */*aad*/,		\
			      const pre##_ocb3key */*key*/);		\
									\
/* --- @pre_ocb3aadhash@ --- *						\
 *									\
 * Arguments:	@pre_ocb3aadctx *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##_ocb3aadhash(pre##_ocb3aadctx */*aad*/,		\
			      const void */*p*/, size_t /*sz*/);	\
									\
/* --- @pre_ocb3init@ --- *						\
 *									\
 * Arguments:	@pre_ocb3ctx *ctx@ = pointer to OCB3 context		\
 *		@const pre_ocb3key *key@ = pointer to key block		\
 *		@const void *n@ = pointer to nonce			\
 *		@size_t nsz@ = size of nonce				\
 *		@size_t tsz@ = tag length				\
 *									\
 * Returns:	Zero on success, @-1@ if the nonce or tag length is	\
 *		bad.							\
 *									\
 * Use:		Initialize an OCB3 operation context with a given key.	\
 *									\
 *		The original key needn't be kept around any more.	\
 */									\
									\
extern int pre##_ocb3init(pre##_ocb3ctx */*ctx*/,			\
			  const pre##_ocb3key */*k*/,			\
			  const void */*n*/, size_t /*nsz*/,		\
			  size_t /*tsz*/);				\
									\
/* --- @pre_ocb3reinit@ --- *						\
 *									\
 * Arguments:	@pre_ocb3ctx *ctx@ = pointer to OCB3 context		\
 *		@const void *n@ = pointer to nonce			\
 *		@size_t nsz@ = size of nonce				\
 *		@size_t tsz@ = tag length				\
 *									\
 * Returns:	Zero on success, @-1@ if the nonce or tag length is	\
 *		bad.							\
 *									\
 * Use:		Reinitialize an OCB3 operation context, changing the	\
 *		nonce and/or tag length.				\
 */									\
									\
extern int pre##_ocb3reinit(pre##_ocb3ctx */*ctx*/,			\
			    const void */*n*/, size_t /*nsz*/,		\
			    size_t /*tsz*/);				\
									\
/* --- @pre_ocb3step@ --- *						\
 *									\
 * Arguments:	@pre_ocb3ctx *ctx@ = pointer to OCB3 context		\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Reinitialize an OCB3 operation context, stepping to	\
 *		the `next' nonce along.					\
 */									\
									\
extern void pre##_ocb3step(pre##_ocb3ctx */*ctx*/);			\
									\
/* --- @pre_ocb3encrypt@ --- *						\
 *									\
 * Arguments:	@pre_ocb3ctx *ctx@ = pointer to OCB3 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 OCB3 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##_ocb3encrypt(pre##_ocb3ctx */*ctx*/,			\
			     const void */*src*/, size_t /*sz*/,	\
			     buf */*dst*/);				\
									\
/* --- @pre_ocb3decrypt@ --- *						\
 *									\
 * Arguments:	@pre_ocb3ctx *ctx@ = pointer to OCB3 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 OCB3 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##_ocb3decrypt(pre##_ocb3ctx */*ctx*/,			\
			     const void */*src*/, size_t /*sz*/,	\
			     buf */*dst*/);				\
									\
/* --- @pre_ocb3encryptdone@ --- *					\
 *									\
 * Arguments:	@pre_ocb3ctx *ctx@ = pointer to an OCB3 context		\
 *		@const pre_ocb3aadctx *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 OCB3 encryption operation.  The @aad@	\
 *		pointer may be null if there is no additional		\
 *		authenticated data.  OCB3 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##_ocb3encryptdone(pre##_ocb3ctx */*ctx*/,		\
				 const pre##_ocb3aadctx */*aad*/,	\
				 buf */*dst*/,				\
				 void */*tag*/, size_t /*tsz*/);	\
									\
/* --- @pre_ocb3decryptdone@ --- *					\
 *									\
 * Arguments:	@pre_ocb3ctx *ctx@ = pointer to an OCB3 context		\
 *		@const pre_ocb3aadctx *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 OCB3 decryption operation.  The @aad@	\
 *		pointer may be null if there is no additional		\
 *		authenticated data.  OCB3 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##_ocb3decryptdone(pre##_ocb3ctx */*ctx*/,		\
				 const pre##_ocb3aadctx */*aad*/,	\
				 buf */*dst*/,				\
				 const void */*tag*/, size_t /*tsz*/);	\
									\
/* --- Generic AEAD interface --- */					\
									\
extern const gcaead pre##_ocb3;

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

#ifdef __cplusplus
  }
#endif

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