/
picotls.h
582 lines (542 loc) · 23.5 KB
/
picotls.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
/*
* Copyright (c) 2016 DeNA Co., Ltd., Kazuho Oku
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to
* deal in the Software without restriction, including without limitation the
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
* sell copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
* IN THE SOFTWARE.
*/
#ifndef picotls_h
#define picotls_h
#include <assert.h>
#include <inttypes.h>
#define PTLS_MAX_SECRET_SIZE 32
#define PTLS_MAX_IV_SIZE 16
#define PTLS_MAX_DIGEST_SIZE 64
#define PTLS_MAX_RECORD_OVERHEAD (5 + 16 + 1) /* maximum per-record overhead (header + tag + type) */
/* cipher-suites */
#define PTLS_CIPHER_SUITE_AES_128_GCM_SHA256 0x1301
#define PTLS_CIPHER_SUITE_AES_256_GCM_SHA384 0x1302
#define PTLS_CIPHER_SUITE_CHACHA20_POLY1305_SHA256 0x1303
/* negotiated_groups */
#define PTLS_GROUP_SECP256R1 23
#define PTLS_GROUP_X25519 29
/* signature algorithms */
#define PTLS_SIGNATURE_RSA_PKCS1_SHA1 0x0201
#define PTLS_SIGNATURE_RSA_PKCS1_SHA256 0x0401
#define PTLS_SIGNATURE_ECDSA_SECP256R1_SHA256 0x0403
#define PTLS_SIGNATURE_RSA_PSS_SHA256 0x0804
/* error classes and macros */
#define PTLS_ERROR_CLASS_SELF_ALERT 0
#define PTLS_ERROR_CLASS_PEER_ALERT 0x100
#define PTLS_ERROR_CLASS_INTERNAL 0x200
#define PTLS_ERROR_GET_CLASS(e) ((e) & ~0xff)
#define PTLS_ALERT_TO_SELF_ERROR(e) ((e) + PTLS_ERROR_CLASS_SELF_ALERT)
#define PTLS_ALERT_TO_PEER_ERROR(e) ((e) + PTLS_ERROR_CLASS_PEER_ALERT)
#define PTLS_ERROR_TO_ALERT(e) ((e)&0xff)
/* alerts */
#define PTLS_ALERT_LEVEL_WARNING 1
#define PTLS_ALERT_LEVEL_FATAL 2
#define PTLS_ALERT_CLOSE_NOTIFY 0
#define PTLS_ALERT_END_OF_EARLY_DATA 1
#define PTLS_ALERT_UNEXPECTED_MESSAGE 10
#define PTLS_ALERT_BAD_RECORD_MAC 20
#define PTLS_ALERT_HANDSHAKE_FAILURE 40
#define PTLS_ALERT_BAD_CERTIFICATE 42
#define PTLS_ALERT_CERTIFICATE_REVOKED 44
#define PTLS_ALERT_CERTIFICATE_EXPIRED 45
#define PTLS_ALERT_CERTIFICATE_UNKNOWN 46
#define PTLS_ALERT_ILLEGAL_PARAMETER 47
#define PTLS_ALERT_DECODE_ERROR 50
#define PTLS_ALERT_DECRYPT_ERROR 51
#define PTLS_ALERT_PROTOCOL_VERSION 70
#define PTLS_ALERT_INTERNAL_ERROR 80
#define PTLS_ALERT_USER_CANCELED 90
#define PTLS_ALERT_MISSING_EXTENSION 109
#define PTLS_ALERT_UNRECOGNIZED_NAME 112
/* internal errors */
#define PTLS_ERROR_NO_MEMORY (PTLS_ERROR_CLASS_INTERNAL + 1)
#define PTLS_ERROR_HANDSHAKE_IN_PROGRESS (PTLS_ERROR_CLASS_INTERNAL + 2)
#define PTLS_ERROR_LIBRARY (PTLS_ERROR_CLASS_INTERNAL + 3)
#define PTLS_ERROR_INCOMPATIBLE_KEY (PTLS_ERROR_CLASS_INTERNAL + 4)
#define PTLS_ERROR_SESSION_NOT_FOUND (PTLS_ERROR_CLASS_INTERNAL + 5)
typedef struct st_ptls_t ptls_t;
/**
* represents a sequence of octets
*/
typedef struct st_ptls_iovec_t {
uint8_t *base;
size_t len;
} ptls_iovec_t;
/**
* used for storing output
*/
typedef struct st_ptls_buffer_t {
uint8_t *base;
size_t capacity;
size_t off;
int is_allocated;
} ptls_buffer_t;
/**
* key exchange context built by ptls_key_exchange_algorithm::create.
*/
typedef struct st_ptls_key_exchange_context_t {
/**
* called once per created context. Callee must free resources allocated to the context and set *keyex to NULL. Secret and
* peerkey will be NULL in case the exchange never happened.
*/
int (*on_exchange)(struct st_ptls_key_exchange_context_t **keyex, ptls_iovec_t *secret, ptls_iovec_t peerkey);
} ptls_key_exchange_context_t;
/**
* A key exchange algorithm.
*/
typedef const struct st_ptls_key_exchange_algorithm_t {
/**
* ID defined by the TLS specification
*/
uint16_t id;
/**
* creates a context for asynchronous key exchange. The function is called when ClientHello is generated. The on_exchange
* callback of the created context is called when the client receives ServerHello.
*/
int (*create)(ptls_key_exchange_context_t **ctx, ptls_iovec_t *pubkey);
/**
* implements synchronous key exchange. Called when receiving a ServerHello.
*/
int (*exchange)(ptls_iovec_t *pubkey, ptls_iovec_t *secret, ptls_iovec_t peerkey);
} ptls_key_exchange_algorithm_t;
/**
* AEAD context. AEAD implementations are allowed to stuff data at the end of the struct. The size of the memory allocated for the
* struct is governed by ptls_aead_algorithm_t::context_size.
*/
typedef struct st_ptls_aead_context_t {
const struct st_ptls_aead_algorithm_t *algo;
uint64_t seq;
uint8_t static_iv[PTLS_MAX_IV_SIZE];
/* field above this line must not be altered by the crypto binding */
void (*dispose_crypto)(struct st_ptls_aead_context_t *ctx);
int (*do_transform)(struct st_ptls_aead_context_t *ctx, void *output, size_t *outlen, const void *input, size_t inlen,
const void *iv, uint8_t enc_content_type);
} ptls_aead_context_t;
/**
* An AEAD cipher.
*/
typedef const struct st_ptls_aead_algorithm_t {
/**
* key size
*/
size_t key_size;
/**
* size of the IV
*/
size_t iv_size;
/**
* size of memory allocated for ptls_aead_context_t. AEAD implementations can set this value to something greater than
* sizeof(ptls_aead_context_t) and stuff additional data at the bottom of the struct.
*/
size_t context_size;
/**
* callback that sets up the crypto
*/
int (*setup_crypto)(ptls_aead_context_t *ctx, int is_enc, const void *key);
} ptls_aead_algorithm_t;
/**
*
*/
typedef enum en_ptls_hash_final_mode_t {
/**
* obtains the digest and frees the context
*/
PTLS_HASH_FINAL_MODE_FREE = 0,
/**
* obtains the digest and reset the context to initial state
*/
PTLS_HASH_FINAL_MODE_RESET = 1,
/**
* obtains the digest while leaving the context as-is
*/
PTLS_HASH_FINAL_MODE_SNAPSHOT = 2
} ptls_hash_final_mode_t;
/**
* A hash context.
*/
typedef struct st_ptls_hash_context_t {
/**
* feeds additional data into the hash context
*/
void (*update)(struct st_ptls_hash_context_t *ctx, const void *src, size_t len);
/**
* returns the digest and performs necessary operation specified by mode
*/
void (* final)(struct st_ptls_hash_context_t *ctx, void *md, ptls_hash_final_mode_t mode);
/**
* creates a copy of the hash context
*/
struct st_ptls_hash_context_t *(*clone_)(struct st_ptls_hash_context_t *src);
} ptls_hash_context_t;
/**
* A hash algorithm and its properties.
*/
typedef const struct st_ptls_hash_algorithm_t {
/**
* block size
*/
size_t block_size;
/**
* digest size
*/
size_t digest_size;
/**
* constructor that creates the hash context
*/
ptls_hash_context_t *(*create)(void);
} ptls_hash_algorithm_t;
typedef const struct st_ptls_cipher_suite_t {
uint16_t id;
ptls_aead_algorithm_t *aead;
ptls_hash_algorithm_t *hash;
} ptls_cipher_suite_t;
#define PTLS_CALLBACK_TYPE(ret, name, ...) \
typedef struct st_ptls_##name##_t { \
ret (*cb)(struct st_ptls_##name##_t * self, __VA_ARGS__); \
} ptls_##name##_t
/**
* after receiving ClientHello, the core calls the optional callback to give a chance to the swap the context depending on the input
* values. The callback is required to call `ptls_set_server_name` if an SNI extension needs to be sent to the client.
*/
PTLS_CALLBACK_TYPE(int, on_client_hello, ptls_t *tls, ptls_iovec_t server_name, const ptls_iovec_t *negotiated_protocols,
size_t num_negotiated_protocols, const uint16_t *signature_algorithms, size_t num_signature_algorithms);
/**
* when gerenating CertificateVerify, the core calls the callback to sign the handshake context using the certificate.
*/
PTLS_CALLBACK_TYPE(int, sign_certificate, ptls_t *tls, uint16_t *selected_algorithm, ptls_buffer_t *output, ptls_iovec_t input,
const uint16_t *algorithms, size_t num_algorithms);
/**
* after receiving Certificate, the core calls the callback to verify the certificate chain and to obtain a pointer to a
* callback that should be used for verifying CertificateVerify. If an error occurs between a successful return from this
* callback to the invocation of the verify_sign callback, verify_sign is called with both data and sign set to an empty buffer.
* The implementor of the callback should use that as the opportunity to free any temporary data allocated for the verify_sign
* callback.
*/
PTLS_CALLBACK_TYPE(int, verify_certificate, ptls_t *tls,
int (**verify_sign)(void *verify_ctx, ptls_iovec_t data, ptls_iovec_t sign), void **verify_data,
ptls_iovec_t *certs, size_t num_certs);
/**
* encrypt-and-signs (or verify-and-decrypts) a ticket (server-only)
*/
PTLS_CALLBACK_TYPE(int, encrypt_ticket, ptls_t *tls, ptls_buffer_t *dst, ptls_iovec_t src);
/**
* saves a ticket (client-only)
*/
PTLS_CALLBACK_TYPE(int, save_ticket, ptls_t *tls, ptls_iovec_t input);
/**
* the configuration
*/
typedef struct st_ptls_context_t {
/**
* PRNG to be used
*/
void (*random_bytes)(void *buf, size_t len);
/**
* list of supported key-exchange algorithms terminated by NULL
*/
ptls_key_exchange_algorithm_t **key_exchanges;
/**
* list of supported cipher-suites terminated by NULL
*/
ptls_cipher_suite_t **cipher_suites;
/**
* list of certificates
*/
struct {
ptls_iovec_t *vec;
size_t count;
} certificates;
/**
*
*/
ptls_on_client_hello_t *on_client_hello;
/**
*
*/
ptls_sign_certificate_t *sign_certificate;
/**
*
*/
ptls_verify_certificate_t *verify_certificate;
/**
* lifetime of a session ticket (server-only)
*/
uint32_t ticket_lifetime;
/**
* maximum permitted size of early data (server-only)
*/
uint32_t max_early_data_size;
/**
* if set, psk handshakes use (ec)dhe
*/
int require_dhe_on_psk;
/**
*
*/
ptls_encrypt_ticket_t *encrypt_ticket;
/**
*
*/
ptls_encrypt_ticket_t *decrypt_ticket;
/**
*
*/
ptls_save_ticket_t *save_ticket;
/**
*
*/
void (*log_secret)(ptls_t *tls, const char *label, ptls_iovec_t secret);
} ptls_context_t;
/**
* optional arguments to client-driven handshake
*/
typedef union st_ptls_handshake_properties_t {
struct {
/**
* list of protocols offered through ALPN
*/
struct {
const ptls_iovec_t *list;
size_t count;
} negotiated_protocols;
/**
* session ticket sent to the application via save_ticket callback
*/
ptls_iovec_t session_ticket;
/**
* pointer to store the maximum size of early-data that can be sent immediately (if NULL, early data is not used)
*/
size_t *max_early_data_size;
/**
*
*/
unsigned early_data_accepted_by_peer : 1;
} client;
struct {
} server;
} ptls_handshake_properties_t;
/**
* builds a new ptls_iovec_t instance using the supplied parameters
*/
static ptls_iovec_t ptls_iovec_init(const void *p, size_t len);
/**
* initializes a buffer, setting the default destination to the small buffer provided as the argument.
*/
static void ptls_buffer_init(ptls_buffer_t *buf, void *smallbuf, size_t smallbuf_size);
/**
* disposes a buffer, freeing resources allocated by the buffer itself (if any)
*/
static void ptls_buffer_dispose(ptls_buffer_t *buf);
/**
* internal
*/
void ptls_buffer__release_memory(ptls_buffer_t *buf);
/**
* reserves space for additional amount of memory
*/
int ptls_buffer_reserve(ptls_buffer_t *buf, size_t delta);
/**
* internal
*/
int ptls_buffer__do_pushv(ptls_buffer_t *buf, const void *src, size_t len);
/**
* internal
*/
int ptls_buffer__adjust_asn1_blocksize(ptls_buffer_t *buf, size_t body_size);
/**
* pushes an unsigned bigint
*/
int ptls_buffer_push_asn1_ubigint(ptls_buffer_t *buf, const void *bignum, size_t size);
#define ptls_buffer_pushv(buf, src, len) \
do { \
if ((ret = ptls_buffer__do_pushv((buf), (src), (len))) != 0) \
goto Exit; \
} while (0)
#define ptls_buffer_push(buf, ...) \
do { \
if ((ret = ptls_buffer__do_pushv((buf), (uint8_t[]){__VA_ARGS__}, sizeof((uint8_t[]){__VA_ARGS__}))) != 0) \
goto Exit; \
} while (0)
#define ptls_buffer_push16(buf, v) \
do { \
uint16_t _v = (v); \
ptls_buffer_push(buf, (uint8_t)(_v >> 8), (uint8_t)_v); \
} while (0)
#define ptls_buffer_push32(buf, v) \
do { \
uint32_t _v = (v); \
ptls_buffer_push(buf, (uint8_t)(_v >> 24), (uint8_t)(_v >> 16), (uint8_t)(_v >> 8), (uint8_t)_v); \
} while (0)
#define ptls_buffer_push64(buf, v) \
do { \
uint64_t _v = (v); \
ptls_buffer_push(buf, (uint8_t)(_v >> 56), (uint8_t)(_v >> 48), (uint8_t)(_v >> 40), (uint8_t)(_v >> 32), \
(uint8_t)(_v >> 24), (uint8_t)(_v >> 16), (uint8_t)(_v >> 8), (uint8_t)_v); \
} while (0)
#define ptls_buffer_push_block(buf, _capacity, block) \
do { \
size_t capacity = (_capacity); \
ptls_buffer_pushv((buf), (uint8_t *)"\0\0\0\0\0\0\0", capacity); \
size_t body_start = (buf)->off; \
do { \
block \
} while (0); \
size_t body_size = (buf)->off - body_start; \
for (; capacity != 0; --capacity) \
(buf)->base[body_start - capacity] = (uint8_t)(body_size >> (8 * (capacity - 1))); \
} while (0)
#define ptls_buffer_push_asn1_block(buf, block) \
do { \
ptls_buffer_push((buf), 0xff); /* dummy */ \
size_t body_start = (buf)->off; \
do { \
block \
} while (0); \
size_t body_size = (buf)->off - body_start; \
if (body_size < 128) { \
(buf)->base[body_start - 1] = (uint8_t)body_size; \
} else { \
if ((ret = ptls_buffer__adjust_asn1_blocksize((buf), body_size)) != 0) \
goto Exit; \
} \
} while (0)
#define ptls_buffer_push_asn1_sequence(buf, block) \
do { \
ptls_buffer_push((buf), 0x30); \
ptls_buffer_push_asn1_block((buf), block); \
} while (0)
/**
* create a object to handle new TLS connection. Client-side of a TLS connection is created if server_name is non-NULL. Otherwise,
* a server-side connection is created.
*/
ptls_t *ptls_new(ptls_context_t *ctx, int is_client);
/**
* releases all resources associated to the object
*/
void ptls_free(ptls_t *tls);
/**
* returns address of the crypto callbacks that the connection is using
*/
ptls_context_t *ptls_get_context(ptls_t *tls);
/**
* updates the context of a connection. Can be called from `on_client_hello` callback.
*/
void ptls_set_context(ptls_t *tls, ptls_context_t *ctx);
/**
* returns the client-random
*/
ptls_iovec_t ptls_get_client_random(ptls_t *tls);
/**
* returns the server-name (NULL if SNI is not used or failed to negotiate)
*/
const char *ptls_get_server_name(ptls_t *tls);
/**
* sets the server-name (for client the value sent in SNI). If server_name_len is zero, then strlen(server_name) is called to
* determine
* the length of the name.
*/
int ptls_set_server_name(ptls_t *tls, const char *server_name, size_t server_name_len);
/**
* returns the negotiated protocol (or NULL)
*/
const char *ptls_get_negotiated_protocol(ptls_t *tls);
/**
* sets the negotiated protocol. If protocol_len is zero, strlen(protocol) is called to determine the length of the protocol name.
*/
int ptls_set_negotiated_protocol(ptls_t *tls, const char *protocol, size_t protocol_len);
/**
* returns if the received data is early data
*/
int ptls_is_early_data(ptls_t *tls);
/**
* proceeds with the handshake, optionally taking some input from peer. The function returns zero in case the handshake completed
* successfully. PTLS_ERROR_HANDSHAKE_IN_PROGRESS is returned in case the handshake is incomplete. Otherwise, an error value is
* returned. The contents of sendbuf should be sent to the client, regardless of whether if an error is returned. inlen is an
* argument used for both input and output. As an input, the arguments takes the size of the data available as input. Upon return
* the value is updated to the number of bytes consumed by the handshake. In case the returned value is
* PTLS_ERROR_HANDSHAKE_IN_PROGRESS there is a guarantee that all the input are consumed (i.e. the value of inlen does not change).
*/
int ptls_handshake(ptls_t *tls, ptls_buffer_t *sendbuf, const void *input, size_t *inlen, ptls_handshake_properties_t *args);
/**
* decrypts the first record within given buffer
*/
int ptls_receive(ptls_t *tls, ptls_buffer_t *plaintextbuf, const void *input, size_t *len);
/**
* encrypts given buffer into multiple TLS records
*/
int ptls_send(ptls_t *tls, ptls_buffer_t *sendbuf, const void *input, size_t inlen);
/**
* sends an alert
*/
int ptls_send_alert(ptls_t *tls, ptls_buffer_t *sendbuf, uint8_t level, uint8_t description);
/**
*
*/
ptls_hash_context_t *ptls_hmac_create(ptls_hash_algorithm_t *algo, const void *key, size_t key_size);
/**
*
*/
int ptls_hkdf_extract(ptls_hash_algorithm_t *hash, void *output, ptls_iovec_t salt, ptls_iovec_t ikm);
/**
*
*/
int ptls_hkdf_expand(ptls_hash_algorithm_t *hash, void *output, size_t outlen, ptls_iovec_t prk, ptls_iovec_t info);
/**
*
*/
ptls_aead_context_t *ptls_aead_new(ptls_aead_algorithm_t *aead, ptls_hash_algorithm_t *hash, int is_enc, const void *secret);
/**
*
*/
void ptls_aead_free(ptls_aead_context_t *ctx);
/**
*
*/
int ptls_aead_transform(ptls_aead_context_t *ctx, void *output, size_t *outlen, const void *input, size_t inlen,
uint8_t enc_content_type);
/**
* clears memory
*/
extern void (*volatile ptls_clear_memory)(void *p, size_t len);
/**
*
*/
static ptls_iovec_t ptls_iovec_init(const void *p, size_t len);
/* inline functions */
inline ptls_iovec_t ptls_iovec_init(const void *p, size_t len)
{
return (ptls_iovec_t){(uint8_t *)p, len};
}
inline void ptls_buffer_init(ptls_buffer_t *buf, void *smallbuf, size_t smallbuf_size)
{
assert(smallbuf != NULL);
buf->base = smallbuf;
buf->off = 0;
buf->capacity = smallbuf_size;
buf->is_allocated = 0;
}
inline void ptls_buffer_dispose(ptls_buffer_t *buf)
{
ptls_buffer__release_memory(buf);
*buf = (ptls_buffer_t){NULL};
}
#endif