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

/*
	ccchacha20poly1305.h
	corecrypto

	Copyright 2014 Apple Inc. All rights reserved.
*/

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

};

extern const struct ccchacha20poly1305_info ccchacha20poly1305_info_default;

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