[apple/xnu.git] / EXTERNAL_HEADERS / corecrypto / ccchacha20poly1305.h

/* Copyright (c) (2016,2017,2018,2019) Apple Inc. All rights reserved.
 *
 * corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which
 * is contained in the License.txt file distributed with corecrypto) and only to 
 * people who accept that license. IMPORTANT:  Any license rights granted to you by 
 * Apple Inc. (if any) are limited to internal use within your organization only on 
 * devices and computers you own or control, for the sole purpose of verifying the 
 * security characteristics and correct functioning of the Apple Software.  You may 
 * not, directly or indirectly, redistribute the Apple Software or any portions thereof.
 */

#ifndef _CORECRYPTO_CCCHACHA20POLY1305_H_
#define _CORECRYPTO_CCCHACHA20POLY1305_H_

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#define CCCHACHA20_KEY_NBYTES 32
#define CCCHACHA20_BLOCK_NBYTES 64
#define CCCHACHA20_BLOCK_NBITS (CCCHACHA20_BLOCK_NBYTES * 8)
#define CCCHACHA20_NONCE_NBYTES 12

typedef struct {
	uint32_t state[16];
	uint8_t	buffer[CCCHACHA20_BLOCK_NBYTES];
	size_t leftover;
} ccchacha20_ctx;

#define CCPOLY1305_TAG_NBYTES 16

typedef struct {
	uint32_t r0, r1, r2, r3, r4;
	uint32_t s1, s2, s3, s4;
	uint32_t h0, h1, h2, h3, h4;
	uint8_t	buf[16];
	size_t buf_used;
	uint8_t	key[16];
} ccpoly1305_ctx;


/*!
 @group		ccchacha20poly1305
 @abstract	Encrypts and authenticates or decrypts and verifies data.
 @discussion	See RFC 7539 for details.

 @warning The key-nonce pair must be unique per encryption.

 @warning A single message can be at most (2^38 - 64) bytes in length.

 The correct sequence of calls to encrypt is:

 @code ccchacha20poly1305_init(...)
 ccchacha20poly1305_setnonce(...)
 ccchacha20poly1305_aad(...)       (may be called zero or more times)
 ccchacha20poly1305_encrypt(...)   (may be called zero or more times)
 ccchacha20poly1305_finalize(...)

 To reuse the context for additional encryptions, follow this sequence:

 @code ccchacha20poly1305_reset(...)
 ccchacha20poly1305_setnonce(...)
 ccchacha20poly1305_aad(...)       (may be called zero or more times)
 ccchacha20poly1305_encrypt(...)   (may be called zero or more times)
 ccchacha20poly1305_finalize(...)

 To decrypt, follow this call sequence:

 @code ccchacha20poly1305_init(...)
 ccchacha20poly1305_setnonce(...)
 ccchacha20poly1305_aad(...)       (may be called zero or more times)
 ccchacha20poly1305_decrypt(...)   (may be called zero or more times)
 ccchacha20poly1305_verify(...)    (returns zero on successful decryption)

 To reuse the context for additional encryptions, follow this sequence:

 @code ccchacha20poly1305_reset(...)
 ccchacha20poly1305_setnonce(...)
 ccchacha20poly1305_aad(...)       (may be called zero or more times)
 ccchacha20poly1305_decrypt(...)   (may be called zero or more times)
 ccchacha20poly1305_verify(...)    (returns zero on successful decryption)
*/

#define CCCHACHA20POLY1305_KEY_NBYTES (CCCHACHA20_KEY_NBYTES)
#define CCCHACHA20POLY1305_NONCE_NBYTES (CCCHACHA20_NONCE_NBYTES)
#define CCCHACHA20POLY1305_TAG_NBYTES (CCPOLY1305_TAG_NBYTES)

/* (2^32 - 1) blocks */
/* (2^38 - 64) bytes */
/* (2^41 - 512) bits */
/* Exceeding this figure breaks confidentiality and authenticity. */
#define CCCHACHA20POLY1305_TEXT_MAX_NBYTES ((1ULL << 38) - 64ULL)

#define CCCHACHA20POLY1305_STATE_SETNONCE 1
#define CCCHACHA20POLY1305_STATE_AAD 2
#define CCCHACHA20POLY1305_STATE_ENCRYPT 3
#define CCCHACHA20POLY1305_STATE_DECRYPT 4
#define CCCHACHA20POLY1305_STATE_FINAL 5

typedef struct {
	ccchacha20_ctx chacha20_ctx;
	ccpoly1305_ctx poly1305_ctx;
	uint64_t aad_nbytes;
	uint64_t text_nbytes;
    uint8_t state;
} ccchacha20poly1305_ctx;

// This is just a stub right now.
// Eventually we will optimize by platform.
struct ccchacha20poly1305_info {

};

const struct ccchacha20poly1305_info *ccchacha20poly1305_info(void);

/*!
 @function   ccchacha20poly1305_init
 @abstract   Initialize a chacha20poly1305 context.

 @param      info       Implementation descriptor
 @param      ctx        Context for this instance
 @param      key        Secret chacha20 key

 @result     0 iff successful.

 @discussion The key is 32 bytes in length.

 @warning The key-nonce pair must be unique per encryption.
 */
int	ccchacha20poly1305_init(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, const uint8_t *key);

/*!
 @function   ccchacha20poly1305_reset
 @abstract   Reset a chacha20poly1305 context for reuse.

 @param      info       Implementation descriptor
 @param      ctx        Context for this instance

 @result     0 iff successful.
 */
int ccchacha20poly1305_reset(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx);

/*!
 @function   ccchacha20poly1305_setnonce
 @abstract   Set the nonce for encryption or decryption.

 @param      info       Implementation descriptor
 @param      ctx        Context for this instance
 @param      nonce      Unique nonce per encryption

 @result     0 iff successful.

 @discussion The nonce is 12 bytes in length.

 @warning The key-nonce pair must be unique per encryption.
 */
int ccchacha20poly1305_setnonce(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, const uint8_t *nonce);
int ccchacha20poly1305_incnonce(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, uint8_t *nonce);

/*!
 @function   ccchacha20poly1305_aad
 @abstract   Authenticate additional data.

 @param      info       Descriptor for the mode
 @param      ctx        Context for this instance
 @param      nbytes     Length of the additional data in bytes
 @param      aad        Additional data to authenticate

 @result     0 iff successful.

 @discussion This is typically used to authenticate data that cannot be encrypted (e.g. packet headers).

 This function may be called zero or more times.
 */
int	ccchacha20poly1305_aad(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, size_t nbytes, const void *aad);

/*!
 @function   ccchacha20poly1305_encrypt
 @abstract   Encrypt data.

 @param      info       Descriptor for the mode
 @param      ctx        Context for this instance
 @param      nbytes     Length of the plaintext in bytes
 @param      ptext      Input plaintext
 @param      ctext      Output ciphertext

 @result     0 iff successful.

 @discussion In-place processing is supported.

 This function may be called zero or more times.
 */
int	ccchacha20poly1305_encrypt(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, size_t nbytes, const void *ptext, void *ctext);

/*!
 @function   ccchacha20poly1305_finalize
 @abstract   Finalize encryption.

 @param      info       Descriptor for the mode
 @param      ctx        Context for this instance
 @param      tag        Generated authentication tag

 @result     0 iff successful.

 @discussion The generated tag is 16 bytes in length.
 */
int	ccchacha20poly1305_finalize(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, uint8_t *tag);

/*!
 @function   ccchacha20poly1305_decrypt
 @abstract   Decrypt data.

 @param      info       Descriptor for the mode
 @param      ctx        Context for this instance
 @param      nbytes     Length of the ciphertext in bytes
 @param      ctext      Input ciphertext
 @param      ptext      Output plaintext

 @result     0 iff successful.

 @discussion In-place processing is supported.

 This function may be called zero or more times.
 */
int	ccchacha20poly1305_decrypt(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, size_t nbytes, const void *ctext, void *ptext);

/*!
 @function   ccchacha20poly1305_verify
 @abstract   Verify authenticity.

 @param      info       Descriptor for the mode
 @param      ctx        Context for this instance
 @param      tag        Expected authentication tag

 @result     0 iff authentic and otherwise successful.

 @discussion The expected tag is 16 bytes in length.
 */
int	ccchacha20poly1305_verify(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, const uint8_t *tag);

/*!
 @function      ccchacha20poly1305_encrypt_oneshot
 @abstract      Encrypt with chacha20poly1305.

 @param      info           Descriptor for the mode
 @param      key            Secret chacha20 key
 @param      nonce          Unique nonce per encryption
 @param      aad_nbytes     Length of the additional data in bytes
 @param      aad            Additional data to authenticate
 @param      ptext_nbytes   Length of the plaintext in bytes
 @param      ptext          Input plaintext
 @param      ctext          Output ciphertext
 @param      tag            Generated authentication tag

 @discussion See RFC 7539 for details.

 The key is 32 bytes in length.

 The nonce is 12 bytes in length.

 The generated tag is 16 bytes in length.

 In-place processing is supported.

 @warning The key-nonce pair must be unique per encryption.

 @warning A single message can be at most (2^38 - 64) bytes in length.
 */
int ccchacha20poly1305_encrypt_oneshot(const struct ccchacha20poly1305_info *info, const uint8_t *key, const uint8_t *nonce, size_t aad_nbytes, const void *aad, size_t ptext_nbytes, const void *ptext, void *ctext, uint8_t *tag);

/*!
 @function      ccchacha20poly1305_decrypt_oneshot
 @abstract      Decrypt with chacha20poly1305.

 @param      info           Descriptor for the mode
 @param      key            Secret chacha20 key
 @param      nonce          Unique nonce per encryption
 @param      aad_nbytes     Length of the additional data in bytes
 @param      aad            Additional data to authenticate
 @param      ctext_nbytes   Length of the ciphertext in bytes
 @param      ctext          Input ciphertext
 @param      ptext          Output plaintext
 @param      tag            Expected authentication tag

 @discussion See RFC 7539 for details.

 The key is 32 bytes in length.

 The nonce is 12 bytes in length.

 The generated tag is 16 bytes in length.

 In-place processing is supported.
 */
int ccchacha20poly1305_decrypt_oneshot(const struct ccchacha20poly1305_info *info, const uint8_t *key, const uint8_t *nonce, size_t aad_nbytes, const void *aad, size_t ctext_nbytes, const void *ctext, void *ptext, const uint8_t *tag);

#endif
Commit	Line	Data
f427ee49 A	1	/* Copyright (c) (2016,2017,2018,2019) Apple Inc. All rights reserved.
	2	*
	3	* corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which
	4	* is contained in the License.txt file distributed with corecrypto) and only to
	5	* people who accept that license. IMPORTANT: Any license rights granted to you by
	6	* Apple Inc. (if any) are limited to internal use within your organization only on
	7	* devices and computers you own or control, for the sole purpose of verifying the
	8	* security characteristics and correct functioning of the Apple Software. You may
	9	* not, directly or indirectly, redistribute the Apple Software or any portions thereof.
	10	*/
5ba3f43e A	11
	12	#ifndef _CORECRYPTO_CCCHACHA20POLY1305_H_
	13	#define _CORECRYPTO_CCCHACHA20POLY1305_H_
	14
	15	#include <stdbool.h>
	16	#include <stddef.h>
	17	#include <stdint.h>
	18
	19	#define CCCHACHA20_KEY_NBYTES 32
	20	#define CCCHACHA20_BLOCK_NBYTES 64
	21	#define CCCHACHA20_BLOCK_NBITS (CCCHACHA20_BLOCK_NBYTES * 8)
	22	#define CCCHACHA20_NONCE_NBYTES 12
	23
	24	typedef struct {
	25	uint32_t state[16];
	26	uint8_t buffer[CCCHACHA20_BLOCK_NBYTES];
	27	size_t leftover;
	28	} ccchacha20_ctx;
	29
	30	#define CCPOLY1305_TAG_NBYTES 16
	31
	32	typedef struct {
	33	uint32_t r0, r1, r2, r3, r4;
	34	uint32_t s1, s2, s3, s4;
	35	uint32_t h0, h1, h2, h3, h4;
	36	uint8_t buf[16];
	37	size_t buf_used;
	38	uint8_t key[16];
	39	} ccpoly1305_ctx;
	40
	41
	42	/*!
	43	@group ccchacha20poly1305
	44	@abstract Encrypts and authenticates or decrypts and verifies data.
	45	@discussion See RFC 7539 for details.
	46
	47	@warning The key-nonce pair must be unique per encryption.
	48
	49	@warning A single message can be at most (2^38 - 64) bytes in length.
	50
	51	The correct sequence of calls to encrypt is:
	52
	53	@code ccchacha20poly1305_init(...)
	54	ccchacha20poly1305_setnonce(...)
	55	ccchacha20poly1305_aad(...) (may be called zero or more times)
	56	ccchacha20poly1305_encrypt(...) (may be called zero or more times)
	57	ccchacha20poly1305_finalize(...)
	58
	59	To reuse the context for additional encryptions, follow this sequence:
	60
	61	@code ccchacha20poly1305_reset(...)
	62	ccchacha20poly1305_setnonce(...)
	63	ccchacha20poly1305_aad(...) (may be called zero or more times)
	64	ccchacha20poly1305_encrypt(...) (may be called zero or more times)
	65	ccchacha20poly1305_finalize(...)
	66
	67	To decrypt, follow this call sequence:
	68
	69	@code ccchacha20poly1305_init(...)
	70	ccchacha20poly1305_setnonce(...)
	71	ccchacha20poly1305_aad(...) (may be called zero or more times)
	72	ccchacha20poly1305_decrypt(...) (may be called zero or more times)
	73	ccchacha20poly1305_verify(...) (returns zero on successful decryption)
	74
75	To reuse the context for additional encryptions, follow this sequence:
76
77	@code ccchacha20poly1305_reset(...)
78	ccchacha20poly1305_setnonce(...)
79	ccchacha20poly1305_aad(...) (may be called zero or more times)
80	ccchacha20poly1305_decrypt(...) (may be called zero or more times)
81	ccchacha20poly1305_verify(...) (returns zero on successful decryption)
82	*/
83
84	#define CCCHACHA20POLY1305_KEY_NBYTES (CCCHACHA20_KEY_NBYTES)
85	#define CCCHACHA20POLY1305_NONCE_NBYTES (CCCHACHA20_NONCE_NBYTES)
86	#define CCCHACHA20POLY1305_TAG_NBYTES (CCPOLY1305_TAG_NBYTES)
87
88	/* (2^32 - 1) blocks */
89	/* (2^38 - 64) bytes */
90	/* (2^41 - 512) bits */
91	/* Exceeding this figure breaks confidentiality and authenticity. */
92	#define CCCHACHA20POLY1305_TEXT_MAX_NBYTES ((1ULL << 38) - 64ULL)
93
94	#define CCCHACHA20POLY1305_STATE_SETNONCE 1
95	#define CCCHACHA20POLY1305_STATE_AAD 2
96	#define CCCHACHA20POLY1305_STATE_ENCRYPT 3
97	#define CCCHACHA20POLY1305_STATE_DECRYPT 4
98	#define CCCHACHA20POLY1305_STATE_FINAL 5
99
100	typedef struct {
101	ccchacha20_ctx chacha20_ctx;
102	ccpoly1305_ctx poly1305_ctx;
103	uint64_t aad_nbytes;
104	uint64_t text_nbytes;
105	uint8_t state;
106	} ccchacha20poly1305_ctx;
107
108	// This is just a stub right now.
109	// Eventually we will optimize by platform.
110	struct ccchacha20poly1305_info {
111
112	};
113
5ba3f43e A	114	const struct ccchacha20poly1305_info *ccchacha20poly1305_info(void);
	115
	116	/*!
	117	@function ccchacha20poly1305_init
	118	@abstract Initialize a chacha20poly1305 context.
	119
	120	@param info Implementation descriptor
	121	@param ctx Context for this instance
	122	@param key Secret chacha20 key
	123
	124	@result 0 iff successful.
	125
	126	@discussion The key is 32 bytes in length.
	127
	128	@warning The key-nonce pair must be unique per encryption.
	129	*/
	130	int ccchacha20poly1305_init(const struct ccchacha20poly1305_info info, ccchacha20poly1305_ctx ctx, const uint8_t *key);
	131
	132	/*!
	133	@function ccchacha20poly1305_reset
	134	@abstract Reset a chacha20poly1305 context for reuse.
	135
	136	@param info Implementation descriptor
	137	@param ctx Context for this instance
	138
	139	@result 0 iff successful.
	140	*/
	141	int ccchacha20poly1305_reset(const struct ccchacha20poly1305_info info, ccchacha20poly1305_ctx ctx);
	142
	143	/*!
	144	@function ccchacha20poly1305_setnonce
	145	@abstract Set the nonce for encryption or decryption.
	146
	147	@param info Implementation descriptor
	148	@param ctx Context for this instance
	149	@param nonce Unique nonce per encryption
	150
	151	@result 0 iff successful.
	152
	153	@discussion The nonce is 12 bytes in length.
	154
	155	@warning The key-nonce pair must be unique per encryption.
	156	*/
	157	int ccchacha20poly1305_setnonce(const struct ccchacha20poly1305_info info, ccchacha20poly1305_ctx ctx, const uint8_t *nonce);
	158	int ccchacha20poly1305_incnonce(const struct ccchacha20poly1305_info info, ccchacha20poly1305_ctx ctx, uint8_t *nonce);
	159
	160	/*!
	161	@function ccchacha20poly1305_aad
	162	@abstract Authenticate additional data.
	163
	164	@param info Descriptor for the mode
	165	@param ctx Context for this instance
	166	@param nbytes Length of the additional data in bytes
	167	@param aad Additional data to authenticate
	168
	169	@result 0 iff successful.
	170
	171	@discussion This is typically used to authenticate data that cannot be encrypted (e.g. packet headers).
	172
	173	This function may be called zero or more times.
	174	*/
	175	int ccchacha20poly1305_aad(const struct ccchacha20poly1305_info info, ccchacha20poly1305_ctx ctx, size_t nbytes, const void *aad);
	176
	177	/*!
178	@function ccchacha20poly1305_encrypt
179	@abstract Encrypt data.
180
181	@param info Descriptor for the mode
182	@param ctx Context for this instance
183	@param nbytes Length of the plaintext in bytes
184	@param ptext Input plaintext
185	@param ctext Output ciphertext
186
187	@result 0 iff successful.
188
189	@discussion In-place processing is supported.
190
191	This function may be called zero or more times.
192	*/
193	int ccchacha20poly1305_encrypt(const struct ccchacha20poly1305_info info, ccchacha20poly1305_ctx ctx, size_t nbytes, const void ptext, void ctext);
194
195	/*!
196	@function ccchacha20poly1305_finalize
197	@abstract Finalize encryption.
198
199	@param info Descriptor for the mode
200	@param ctx Context for this instance
201	@param tag Generated authentication tag
202
203	@result 0 iff successful.
204
205	@discussion The generated tag is 16 bytes in length.
206	*/
207	int ccchacha20poly1305_finalize(const struct ccchacha20poly1305_info info, ccchacha20poly1305_ctx ctx, uint8_t *tag);
208
209	/*!
210	@function ccchacha20poly1305_decrypt
211	@abstract Decrypt data.
212
213	@param info Descriptor for the mode
214	@param ctx Context for this instance
215	@param nbytes Length of the ciphertext in bytes
216	@param ctext Input ciphertext
217	@param ptext Output plaintext
218
219	@result 0 iff successful.
220
221	@discussion In-place processing is supported.
222
223	This function may be called zero or more times.
224	*/
225	int ccchacha20poly1305_decrypt(const struct ccchacha20poly1305_info info, ccchacha20poly1305_ctx ctx, size_t nbytes, const void ctext, void ptext);
226
227	/*!
228	@function ccchacha20poly1305_verify
229	@abstract Verify authenticity.
230
231	@param info Descriptor for the mode
232	@param ctx Context for this instance
233	@param tag Expected authentication tag
234
235	@result 0 iff authentic and otherwise successful.
236
237	@discussion The expected tag is 16 bytes in length.
238	*/
239	int ccchacha20poly1305_verify(const struct ccchacha20poly1305_info info, ccchacha20poly1305_ctx ctx, const uint8_t *tag);
240
241	/*!
242	@function ccchacha20poly1305_encrypt_oneshot
243	@abstract Encrypt with chacha20poly1305.
244
245	@param info Descriptor for the mode
246	@param key Secret chacha20 key
247	@param nonce Unique nonce per encryption
248	@param aad_nbytes Length of the additional data in bytes
249	@param aad Additional data to authenticate
250	@param ptext_nbytes Length of the plaintext in bytes
251	@param ptext Input plaintext
252	@param ctext Output ciphertext
253	@param tag Generated authentication tag
254
255	@discussion See RFC 7539 for details.
256
257	The key is 32 bytes in length.
258
259	The nonce is 12 bytes in length.
260
261	The generated tag is 16 bytes in length.
262
263	In-place processing is supported.
264
265	@warning The key-nonce pair must be unique per encryption.
266
267	@warning A single message can be at most (2^38 - 64) bytes in length.
268	*/
269	int ccchacha20poly1305_encrypt_oneshot(const struct ccchacha20poly1305_info info, const uint8_t key, const uint8_t nonce, size_t aad_nbytes, const void aad, size_t ptext_nbytes, const void ptext, void ctext, uint8_t *tag);
270
271	/*!
272	@function ccchacha20poly1305_decrypt_oneshot
273	@abstract Decrypt with chacha20poly1305.
274
275	@param info Descriptor for the mode
276	@param key Secret chacha20 key
277	@param nonce Unique nonce per encryption
278	@param aad_nbytes Length of the additional data in bytes
279	@param aad Additional data to authenticate
280	@param ctext_nbytes Length of the ciphertext in bytes
281	@param ctext Input ciphertext
282	@param ptext Output plaintext
283	@param tag Expected authentication tag
284
285	@discussion See RFC 7539 for details.
286
287	The key is 32 bytes in length.
288
289	The nonce is 12 bytes in length.
290
291	The generated tag is 16 bytes in length.
292
293	In-place processing is supported.
294	*/
295	int ccchacha20poly1305_decrypt_oneshot(const struct ccchacha20poly1305_info info, const uint8_t key, const uint8_t nonce, size_t aad_nbytes, const void aad, size_t ctext_nbytes, const void ctext, void ptext, const uint8_t *tag);
296
297	#endif