Fixed description of TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 in the command-line...
[BearSSL] / inc / bearssl_ssl.h
1 /*
2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24
25 #ifndef BR_BEARSSL_SSL_H__
26 #define BR_BEARSSL_SSL_H__
27
28 #include <stddef.h>
29 #include <stdint.h>
30
31 #include "bearssl_block.h"
32 #include "bearssl_hash.h"
33 #include "bearssl_hmac.h"
34 #include "bearssl_prf.h"
35 #include "bearssl_rand.h"
36 #include "bearssl_x509.h"
37
38 /** \file bearssl_ssl.h
39 *
40 * # SSL
41 *
42 * For an overview of the SSL/TLS API, see [the BearSSL Web
43 * site](https://www.bearssl.org/api1.html).
44 *
45 * The `BR_TLS_*` constants correspond to the standard cipher suites and
46 * their values in the [IANA
47 * registry](http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4).
48 *
49 * The `BR_ALERT_*` constants are for standard TLS alert messages. When
50 * a fatal alert message is sent of received, then the SSL engine context
51 * status is set to the sum of that alert value (an integer in the 0..255
52 * range) and a fixed offset (`BR_ERR_SEND_FATAL_ALERT` for a sent alert,
53 * `BR_ERR_RECV_FATAL_ALERT` for a received alert).
54 */
55
56 /** \brief Optimal input buffer size. */
57 #define BR_SSL_BUFSIZE_INPUT (16384 + 325)
58
59 /** \brief Optimal output buffer size. */
60 #define BR_SSL_BUFSIZE_OUTPUT (16384 + 85)
61
62 /** \brief Optimal buffer size for monodirectional engine
63 (shared input/output buffer). */
64 #define BR_SSL_BUFSIZE_MONO BR_SSL_BUFSIZE_INPUT
65
66 /** \brief Optimal buffer size for bidirectional engine
67 (single buffer split into two separate input/output buffers). */
68 #define BR_SSL_BUFSIZE_BIDI (BR_SSL_BUFSIZE_INPUT + BR_SSL_BUFSIZE_OUTPUT)
69
70 /*
71 * Constants for known SSL/TLS protocol versions (SSL 3.0, TLS 1.0, TLS 1.1
72 * and TLS 1.2). Note that though there is a constant for SSL 3.0, that
73 * protocol version is not actually supported.
74 */
75
76 /** \brief Protocol version: SSL 3.0 (unsupported). */
77 #define BR_SSL30 0x0300
78 /** \brief Protocol version: TLS 1.0. */
79 #define BR_TLS10 0x0301
80 /** \brief Protocol version: TLS 1.1. */
81 #define BR_TLS11 0x0302
82 /** \brief Protocol version: TLS 1.2. */
83 #define BR_TLS12 0x0303
84
85 /*
86 * Error constants. They are used to report the reason why a context has
87 * been marked as failed.
88 *
89 * Implementation note: SSL-level error codes should be in the 1..31
90 * range. The 32..63 range is for certificate decoding and validation
91 * errors. Received fatal alerts imply an error code in the 256..511 range.
92 */
93
94 /** \brief SSL status: no error so far (0). */
95 #define BR_ERR_OK 0
96
97 /** \brief SSL status: caller-provided parameter is incorrect. */
98 #define BR_ERR_BAD_PARAM 1
99
100 /** \brief SSL status: operation requested by the caller cannot be applied
101 with the current context state (e.g. reading data while outgoing data
102 is waiting to be sent). */
103 #define BR_ERR_BAD_STATE 2
104
105 /** \brief SSL status: incoming protocol or record version is unsupported. */
106 #define BR_ERR_UNSUPPORTED_VERSION 3
107
108 /** \brief SSL status: incoming record version does not match the expected
109 version. */
110 #define BR_ERR_BAD_VERSION 4
111
112 /** \brief SSL status: incoming record length is invalid. */
113 #define BR_ERR_BAD_LENGTH 5
114
115 /** \brief SSL status: incoming record is too large to be processed, or
116 buffer is too small for the handshake message to send. */
117 #define BR_ERR_TOO_LARGE 6
118
119 /** \brief SSL status: decryption found an invalid padding, or the record
120 MAC is not correct. */
121 #define BR_ERR_BAD_MAC 7
122
123 /** \brief SSL status: no initial entropy was provided, and none can be
124 obtained from the OS. */
125 #define BR_ERR_NO_RANDOM 8
126
127 /** \brief SSL status: incoming record type is unknown. */
128 #define BR_ERR_UNKNOWN_TYPE 9
129
130 /** \brief SSL status: incoming record or message has wrong type with
131 regards to the current engine state. */
132 #define BR_ERR_UNEXPECTED 10
133
134 /** \brief SSL status: ChangeCipherSpec message from the peer has invalid
135 contents. */
136 #define BR_ERR_BAD_CCS 12
137
138 /** \brief SSL status: alert message from the peer has invalid contents
139 (odd length). */
140 #define BR_ERR_BAD_ALERT 13
141
142 /** \brief SSL status: incoming handshake message decoding failed. */
143 #define BR_ERR_BAD_HANDSHAKE 14
144
145 /** \brief SSL status: ServerHello contains a session ID which is larger
146 than 32 bytes. */
147 #define BR_ERR_OVERSIZED_ID 15
148
149 /** \brief SSL status: server wants to use a cipher suite that we did
150 not claim to support. This is also reported if we tried to advertise
151 a cipher suite that we do not support. */
152 #define BR_ERR_BAD_CIPHER_SUITE 16
153
154 /** \brief SSL status: server wants to use a compression that we did not
155 claim to support. */
156 #define BR_ERR_BAD_COMPRESSION 17
157
158 /** \brief SSL status: server's max fragment length does not match
159 client's. */
160 #define BR_ERR_BAD_FRAGLEN 18
161
162 /** \brief SSL status: secure renegotiation failed. */
163 #define BR_ERR_BAD_SECRENEG 19
164
165 /** \brief SSL status: server sent an extension type that we did not
166 announce, or used the same extension type several times in a single
167 ServerHello. */
168 #define BR_ERR_EXTRA_EXTENSION 20
169
170 /** \brief SSL status: invalid Server Name Indication contents (when
171 used by the server, this extension shall be empty). */
172 #define BR_ERR_BAD_SNI 21
173
174 /** \brief SSL status: invalid ServerHelloDone from the server (length
175 is not 0). */
176 #define BR_ERR_BAD_HELLO_DONE 22
177
178 /** \brief SSL status: internal limit exceeded (e.g. server's public key
179 is too large). */
180 #define BR_ERR_LIMIT_EXCEEDED 23
181
182 /** \brief SSL status: Finished message from peer does not match the
183 expected value. */
184 #define BR_ERR_BAD_FINISHED 24
185
186 /** \brief SSL status: session resumption attempt with distinct version
187 or cipher suite. */
188 #define BR_ERR_RESUME_MISMATCH 25
189
190 /** \brief SSL status: unsupported or invalid algorithm (ECDHE curve,
191 signature algorithm, hash function). */
192 #define BR_ERR_INVALID_ALGORITHM 26
193
194 /** \brief SSL status: invalid signature (on ServerKeyExchange from
195 server, or in CertificateVerify from client). */
196 #define BR_ERR_BAD_SIGNATURE 27
197
198 /** \brief SSL status: peer's public key does not have the proper type
199 or is not allowed for requested operation. */
200 #define BR_ERR_WRONG_KEY_USAGE 28
201
202 /** \brief SSL status: client did not send a certificate upon request,
203 or the client certificate could not be validated. */
204 #define BR_ERR_NO_CLIENT_AUTH 29
205
206 /** \brief SSL status: I/O error or premature close on underlying
207 transport stream. This error code is set only by the simplified
208 I/O API ("br_sslio_*"). */
209 #define BR_ERR_IO 31
210
211 /** \brief SSL status: base value for a received fatal alert.
212
213 When a fatal alert is received from the peer, the alert value
214 is added to this constant. */
215 #define BR_ERR_RECV_FATAL_ALERT 256
216
217 /** \brief SSL status: base value for a sent fatal alert.
218
219 When a fatal alert is sent to the peer, the alert value is added
220 to this constant. */
221 #define BR_ERR_SEND_FATAL_ALERT 512
222
223 /* ===================================================================== */
224
225 /**
226 * \brief Decryption engine for SSL.
227 *
228 * When processing incoming records, the SSL engine will use a decryption
229 * engine that uses a specific context structure, and has a set of
230 * methods (a vtable) that follows this template.
231 *
232 * The decryption engine is responsible for applying decryption, verifying
233 * MAC, and keeping track of the record sequence number.
234 */
235 typedef struct br_sslrec_in_class_ br_sslrec_in_class;
236 struct br_sslrec_in_class_ {
237 /**
238 * \brief Context size (in bytes).
239 */
240 size_t context_size;
241
242 /**
243 * \brief Test validity of the incoming record length.
244 *
245 * This function returns 1 if the announced length for an
246 * incoming record is valid, 0 otherwise,
247 *
248 * \param ctx decryption engine context.
249 * \param record_len incoming record length.
250 * \return 1 of a valid length, 0 otherwise.
251 */
252 int (*check_length)(const br_sslrec_in_class *const *ctx,
253 size_t record_len);
254
255 /**
256 * \brief Decrypt the incoming record.
257 *
258 * This function may assume that the record length is valid
259 * (it has been previously tested with `check_length()`).
260 * Decryption is done in place; `*len` is updated with the
261 * cleartext length, and the address of the first plaintext
262 * byte is returned. If the record is correct but empty, then
263 * `*len` is set to 0 and a non-`NULL` pointer is returned.
264 *
265 * On decryption/MAC error, `NULL` is returned.
266 *
267 * \param ctx decryption engine context.
268 * \param record_type record type (23 for application data, etc).
269 * \param version record version.
270 * \param payload address of encrypted payload.
271 * \param len pointer to payload length (updated).
272 * \return pointer to plaintext, or `NULL` on error.
273 */
274 unsigned char *(*decrypt)(const br_sslrec_in_class **ctx,
275 int record_type, unsigned version,
276 void *payload, size_t *len);
277 };
278
279 /**
280 * \brief Encryption engine for SSL.
281 *
282 * When building outgoing records, the SSL engine will use an encryption
283 * engine that uses a specific context structure, and has a set of
284 * methods (a vtable) that follows this template.
285 *
286 * The encryption engine is responsible for applying encryption and MAC,
287 * and keeping track of the record sequence number.
288 */
289 typedef struct br_sslrec_out_class_ br_sslrec_out_class;
290 struct br_sslrec_out_class_ {
291 /**
292 * \brief Context size (in bytes).
293 */
294 size_t context_size;
295
296 /**
297 * \brief Compute maximum plaintext sizes and offsets.
298 *
299 * When this function is called, the `*start` and `*end`
300 * values contain offsets designating the free area in the
301 * outgoing buffer for plaintext data; that free area is
302 * preceded by a 5-byte space which will receive the record
303 * header.
304 *
305 * The `max_plaintext()` function is responsible for adjusting
306 * both `*start` and `*end` to make room for any record-specific
307 * header, MAC, padding, and possible split.
308 *
309 * \param ctx encryption engine context.
310 * \param start pointer to start of plaintext offset (updated).
311 * \param end pointer to start of plaintext offset (updated).
312 */
313 void (*max_plaintext)(const br_sslrec_out_class *const *ctx,
314 size_t *start, size_t *end);
315
316 /**
317 * \brief Perform record encryption.
318 *
319 * This function encrypts the record. The plaintext address and
320 * length are provided. Returned value is the start of the
321 * encrypted record (or sequence of records, if a split was
322 * performed), _including_ the 5-byte header, and `*len` is
323 * adjusted to the total size of the record(s), there again
324 * including the header(s).
325 *
326 * \param ctx decryption engine context.
327 * \param record_type record type (23 for application data, etc).
328 * \param version record version.
329 * \param plaintext address of plaintext.
330 * \param len pointer to plaintext length (updated).
331 * \return pointer to start of built record.
332 */
333 unsigned char *(*encrypt)(const br_sslrec_out_class **ctx,
334 int record_type, unsigned version,
335 void *plaintext, size_t *len);
336 };
337
338 /**
339 * \brief Context for a no-encryption engine.
340 *
341 * The no-encryption engine processes outgoing records during the initial
342 * handshake, before encryption is applied.
343 */
344 typedef struct {
345 /** \brief No-encryption engine vtable. */
346 const br_sslrec_out_class *vtable;
347 } br_sslrec_out_clear_context;
348
349 /** \brief Static, constant vtable for the no-encryption engine. */
350 extern const br_sslrec_out_class br_sslrec_out_clear_vtable;
351
352 /* ===================================================================== */
353
354 /**
355 * \brief Record decryption engine class, for CBC mode.
356 *
357 * This class type extends the decryption engine class with an
358 * initialisation method that receives the parameters needed
359 * for CBC processing: block cipher implementation, block cipher key,
360 * HMAC parameters (hash function, key, MAC length), and IV. If the
361 * IV is `NULL`, then a per-record IV will be used (TLS 1.1+).
362 */
363 typedef struct br_sslrec_in_cbc_class_ br_sslrec_in_cbc_class;
364 struct br_sslrec_in_cbc_class_ {
365 /**
366 * \brief Superclass, as first vtable field.
367 */
368 br_sslrec_in_class inner;
369
370 /**
371 * \brief Engine initialisation method.
372 *
373 * This method sets the vtable field in the context.
374 *
375 * \param ctx context to initialise.
376 * \param bc_impl block cipher implementation (CBC decryption).
377 * \param bc_key block cipher key.
378 * \param bc_key_len block cipher key length (in bytes).
379 * \param dig_impl hash function for HMAC.
380 * \param mac_key HMAC key.
381 * \param mac_key_len HMAC key length (in bytes).
382 * \param mac_out_len HMAC output length (in bytes).
383 * \param iv initial IV (or `NULL`).
384 */
385 void (*init)(const br_sslrec_in_cbc_class **ctx,
386 const br_block_cbcdec_class *bc_impl,
387 const void *bc_key, size_t bc_key_len,
388 const br_hash_class *dig_impl,
389 const void *mac_key, size_t mac_key_len, size_t mac_out_len,
390 const void *iv);
391 };
392
393 /**
394 * \brief Record encryption engine class, for CBC mode.
395 *
396 * This class type extends the encryption engine class with an
397 * initialisation method that receives the parameters needed
398 * for CBC processing: block cipher implementation, block cipher key,
399 * HMAC parameters (hash function, key, MAC length), and IV. If the
400 * IV is `NULL`, then a per-record IV will be used (TLS 1.1+).
401 */
402 typedef struct br_sslrec_out_cbc_class_ br_sslrec_out_cbc_class;
403 struct br_sslrec_out_cbc_class_ {
404 /**
405 * \brief Superclass, as first vtable field.
406 */
407 br_sslrec_out_class inner;
408
409 /**
410 * \brief Engine initialisation method.
411 *
412 * This method sets the vtable field in the context.
413 *
414 * \param ctx context to initialise.
415 * \param bc_impl block cipher implementation (CBC encryption).
416 * \param bc_key block cipher key.
417 * \param bc_key_len block cipher key length (in bytes).
418 * \param dig_impl hash function for HMAC.
419 * \param mac_key HMAC key.
420 * \param mac_key_len HMAC key length (in bytes).
421 * \param mac_out_len HMAC output length (in bytes).
422 * \param iv initial IV (or `NULL`).
423 */
424 void (*init)(const br_sslrec_out_cbc_class **ctx,
425 const br_block_cbcenc_class *bc_impl,
426 const void *bc_key, size_t bc_key_len,
427 const br_hash_class *dig_impl,
428 const void *mac_key, size_t mac_key_len, size_t mac_out_len,
429 const void *iv);
430 };
431
432 /**
433 * \brief Context structure for decrypting incoming records with
434 * CBC + HMAC.
435 *
436 * The first field points to the vtable. The other fields are opaque
437 * and shall not be accessed directly.
438 */
439 typedef struct {
440 /** \brief Pointer to vtable. */
441 const br_sslrec_in_cbc_class *vtable;
442 #ifndef BR_DOXYGEN_IGNORE
443 uint64_t seq;
444 union {
445 const br_block_cbcdec_class *vtable;
446 br_aes_gen_cbcdec_keys aes;
447 br_des_gen_cbcdec_keys des;
448 } bc;
449 br_hmac_key_context mac;
450 size_t mac_len;
451 unsigned char iv[16];
452 int explicit_IV;
453 #endif
454 } br_sslrec_in_cbc_context;
455
456 /**
457 * \brief Static, constant vtable for record decryption with CBC.
458 */
459 extern const br_sslrec_in_cbc_class br_sslrec_in_cbc_vtable;
460
461 /**
462 * \brief Context structure for encrypting outgoing records with
463 * CBC + HMAC.
464 *
465 * The first field points to the vtable. The other fields are opaque
466 * and shall not be accessed directly.
467 */
468 typedef struct {
469 /** \brief Pointer to vtable. */
470 const br_sslrec_out_cbc_class *vtable;
471 #ifndef BR_DOXYGEN_IGNORE
472 uint64_t seq;
473 union {
474 const br_block_cbcenc_class *vtable;
475 br_aes_gen_cbcenc_keys aes;
476 br_des_gen_cbcenc_keys des;
477 } bc;
478 br_hmac_key_context mac;
479 size_t mac_len;
480 unsigned char iv[16];
481 int explicit_IV;
482 #endif
483 } br_sslrec_out_cbc_context;
484
485 /**
486 * \brief Static, constant vtable for record encryption with CBC.
487 */
488 extern const br_sslrec_out_cbc_class br_sslrec_out_cbc_vtable;
489
490 /* ===================================================================== */
491
492 /**
493 * \brief Record decryption engine class, for GCM mode.
494 *
495 * This class type extends the decryption engine class with an
496 * initialisation method that receives the parameters needed
497 * for GCM processing: block cipher implementation, block cipher key,
498 * GHASH implementation, and 4-byte IV.
499 */
500 typedef struct br_sslrec_in_gcm_class_ br_sslrec_in_gcm_class;
501 struct br_sslrec_in_gcm_class_ {
502 /**
503 * \brief Superclass, as first vtable field.
504 */
505 br_sslrec_in_class inner;
506
507 /**
508 * \brief Engine initialisation method.
509 *
510 * This method sets the vtable field in the context.
511 *
512 * \param ctx context to initialise.
513 * \param bc_impl block cipher implementation (CTR).
514 * \param key block cipher key.
515 * \param key_len block cipher key length (in bytes).
516 * \param gh_impl GHASH implementation.
517 * \param iv static IV (4 bytes).
518 */
519 void (*init)(const br_sslrec_in_gcm_class **ctx,
520 const br_block_ctr_class *bc_impl,
521 const void *key, size_t key_len,
522 br_ghash gh_impl,
523 const void *iv);
524 };
525
526 /**
527 * \brief Record encryption engine class, for GCM mode.
528 *
529 * This class type extends the encryption engine class with an
530 * initialisation method that receives the parameters needed
531 * for GCM processing: block cipher implementation, block cipher key,
532 * GHASH implementation, and 4-byte IV.
533 */
534 typedef struct br_sslrec_out_gcm_class_ br_sslrec_out_gcm_class;
535 struct br_sslrec_out_gcm_class_ {
536 /**
537 * \brief Superclass, as first vtable field.
538 */
539 br_sslrec_out_class inner;
540
541 /**
542 * \brief Engine initialisation method.
543 *
544 * This method sets the vtable field in the context.
545 *
546 * \param ctx context to initialise.
547 * \param bc_impl block cipher implementation (CTR).
548 * \param key block cipher key.
549 * \param key_len block cipher key length (in bytes).
550 * \param gh_impl GHASH implementation.
551 * \param iv static IV (4 bytes).
552 */
553 void (*init)(const br_sslrec_out_gcm_class **ctx,
554 const br_block_ctr_class *bc_impl,
555 const void *key, size_t key_len,
556 br_ghash gh_impl,
557 const void *iv);
558 };
559
560 /**
561 * \brief Context structure for processing records with GCM.
562 *
563 * The same context structure is used for encrypting and decrypting.
564 *
565 * The first field points to the vtable. The other fields are opaque
566 * and shall not be accessed directly.
567 */
568 typedef struct {
569 /** \brief Pointer to vtable. */
570 union {
571 const void *gen;
572 const br_sslrec_in_gcm_class *in;
573 const br_sslrec_out_gcm_class *out;
574 } vtable;
575 #ifndef BR_DOXYGEN_IGNORE
576 uint64_t seq;
577 union {
578 const br_block_ctr_class *vtable;
579 br_aes_gen_ctr_keys aes;
580 } bc;
581 br_ghash gh;
582 unsigned char iv[4];
583 unsigned char h[16];
584 #endif
585 } br_sslrec_gcm_context;
586
587 /**
588 * \brief Static, constant vtable for record decryption with GCM.
589 */
590 extern const br_sslrec_in_gcm_class br_sslrec_in_gcm_vtable;
591
592 /**
593 * \brief Static, constant vtable for record encryption with GCM.
594 */
595 extern const br_sslrec_out_gcm_class br_sslrec_out_gcm_vtable;
596
597 /* ===================================================================== */
598
599 /**
600 * \brief Record decryption engine class, for ChaCha20+Poly1305.
601 *
602 * This class type extends the decryption engine class with an
603 * initialisation method that receives the parameters needed
604 * for ChaCha20+Poly1305 processing: ChaCha20 implementation,
605 * Poly1305 implementation, key, and 12-byte IV.
606 */
607 typedef struct br_sslrec_in_chapol_class_ br_sslrec_in_chapol_class;
608 struct br_sslrec_in_chapol_class_ {
609 /**
610 * \brief Superclass, as first vtable field.
611 */
612 br_sslrec_in_class inner;
613
614 /**
615 * \brief Engine initialisation method.
616 *
617 * This method sets the vtable field in the context.
618 *
619 * \param ctx context to initialise.
620 * \param ichacha ChaCha20 implementation.
621 * \param ipoly Poly1305 implementation.
622 * \param key secret key (32 bytes).
623 * \param iv static IV (12 bytes).
624 */
625 void (*init)(const br_sslrec_in_chapol_class **ctx,
626 br_chacha20_run ichacha,
627 br_poly1305_run ipoly,
628 const void *key, const void *iv);
629 };
630
631 /**
632 * \brief Record encryption engine class, for ChaCha20+Poly1305.
633 *
634 * This class type extends the encryption engine class with an
635 * initialisation method that receives the parameters needed
636 * for ChaCha20+Poly1305 processing: ChaCha20 implementation,
637 * Poly1305 implementation, key, and 12-byte IV.
638 */
639 typedef struct br_sslrec_out_chapol_class_ br_sslrec_out_chapol_class;
640 struct br_sslrec_out_chapol_class_ {
641 /**
642 * \brief Superclass, as first vtable field.
643 */
644 br_sslrec_out_class inner;
645
646 /**
647 * \brief Engine initialisation method.
648 *
649 * This method sets the vtable field in the context.
650 *
651 * \param ctx context to initialise.
652 * \param ichacha ChaCha20 implementation.
653 * \param ipoly Poly1305 implementation.
654 * \param key secret key (32 bytes).
655 * \param iv static IV (12 bytes).
656 */
657 void (*init)(const br_sslrec_out_chapol_class **ctx,
658 br_chacha20_run ichacha,
659 br_poly1305_run ipoly,
660 const void *key, const void *iv);
661 };
662
663 /**
664 * \brief Context structure for processing records with ChaCha20+Poly1305.
665 *
666 * The same context structure is used for encrypting and decrypting.
667 *
668 * The first field points to the vtable. The other fields are opaque
669 * and shall not be accessed directly.
670 */
671 typedef struct {
672 /** \brief Pointer to vtable. */
673 union {
674 const void *gen;
675 const br_sslrec_in_chapol_class *in;
676 const br_sslrec_out_chapol_class *out;
677 } vtable;
678 #ifndef BR_DOXYGEN_IGNORE
679 uint64_t seq;
680 unsigned char key[32];
681 unsigned char iv[12];
682 br_chacha20_run ichacha;
683 br_poly1305_run ipoly;
684 #endif
685 } br_sslrec_chapol_context;
686
687 /**
688 * \brief Static, constant vtable for record decryption with ChaCha20+Poly1305.
689 */
690 extern const br_sslrec_in_chapol_class br_sslrec_in_chapol_vtable;
691
692 /**
693 * \brief Static, constant vtable for record encryption with ChaCha20+Poly1305.
694 */
695 extern const br_sslrec_out_chapol_class br_sslrec_out_chapol_vtable;
696
697 /* ===================================================================== */
698
699 /**
700 * \brief Type for session parameters, to be saved for session resumption.
701 */
702 typedef struct {
703 /** \brief Session ID buffer. */
704 unsigned char session_id[32];
705 /** \brief Session ID length (in bytes, at most 32). */
706 unsigned char session_id_len;
707 /** \brief Protocol version. */
708 uint16_t version;
709 /** \brief Cipher suite. */
710 uint16_t cipher_suite;
711 /** \brief Master secret. */
712 unsigned char master_secret[48];
713 } br_ssl_session_parameters;
714
715 #ifndef BR_DOXYGEN_IGNORE
716 /*
717 * Maximum numnber of cipher suites supported by a client or server.
718 */
719 #define BR_MAX_CIPHER_SUITES 40
720 #endif
721
722 /**
723 * \brief Context structure for SSL engine.
724 *
725 * This strucuture is common to the client and server; both the client
726 * context (`br_ssl_client_context`) and the server context
727 * (`br_ssl_server_context`) include a `br_ssl_engine_context` as their
728 * first field.
729 *
730 * The engine context manages records, including alerts, closures, and
731 * transitions to new encryption/MAC algorithms. Processing of handshake
732 * records is delegated to externally provided code. This structure
733 * should not be used directly.
734 *
735 * Structure contents are opaque and shall not be accessed directly.
736 */
737 typedef struct {
738 #ifndef BR_DOXYGEN_IGNORE
739 /*
740 * The error code. When non-zero, then the state is "failed" and
741 * no I/O may occur until reset.
742 */
743 int err;
744
745 /*
746 * Configured I/O buffers. They are either disjoint, or identical.
747 */
748 unsigned char *ibuf, *obuf;
749 size_t ibuf_len, obuf_len;
750
751 /*
752 * Maximum fragment length applies to outgoing records; incoming
753 * records can be processed as long as they fit in the input
754 * buffer. It is guaranteed that incoming records at least as big
755 * as max_frag_len can be processed.
756 */
757 uint16_t max_frag_len;
758 unsigned char log_max_frag_len;
759 unsigned char peer_log_max_frag_len;
760
761 /*
762 * Buffering management registers.
763 */
764 size_t ixa, ixb, ixc;
765 size_t oxa, oxb, oxc;
766 unsigned char iomode;
767 unsigned char incrypt;
768
769 /*
770 * Shutdown flag: when set to non-zero, incoming record bytes
771 * will not be accepted anymore. This is used after a close_notify
772 * has been received: afterwards, the engine no longer claims that
773 * it could receive bytes from the transport medium.
774 */
775 unsigned char shutdown_recv;
776
777 /*
778 * 'record_type_in' is set to the incoming record type when the
779 * record header has been received.
780 * 'record_type_out' is used to make the next outgoing record
781 * header when it is ready to go.
782 */
783 unsigned char record_type_in, record_type_out;
784
785 /*
786 * When a record is received, its version is extracted:
787 * -- if 'version_in' is 0, then it is set to the received version;
788 * -- otherwise, if the received version is not identical to
789 * the 'version_in' contents, then a failure is reported.
790 *
791 * This implements the SSL requirement that all records shall
792 * use the negotiated protocol version, once decided (in the
793 * ServerHello). It is up to the handshake handler to adjust this
794 * field when necessary.
795 */
796 uint16_t version_in;
797
798 /*
799 * 'version_out' is used when the next outgoing record is ready
800 * to go.
801 */
802 uint16_t version_out;
803
804 /*
805 * Record handler contexts.
806 */
807 union {
808 const br_sslrec_in_class *vtable;
809 br_sslrec_in_cbc_context cbc;
810 br_sslrec_gcm_context gcm;
811 br_sslrec_chapol_context chapol;
812 } in;
813 union {
814 const br_sslrec_out_class *vtable;
815 br_sslrec_out_clear_context clear;
816 br_sslrec_out_cbc_context cbc;
817 br_sslrec_gcm_context gcm;
818 br_sslrec_chapol_context chapol;
819 } out;
820
821 /*
822 * The "application data" flag. It is set when application data
823 * can be exchanged, cleared otherwise.
824 */
825 unsigned char application_data;
826
827 /*
828 * Context RNG.
829 */
830 br_hmac_drbg_context rng;
831 int rng_init_done;
832 int rng_os_rand_done;
833
834 /*
835 * Supported minimum and maximum versions, and cipher suites.
836 */
837 uint16_t version_min;
838 uint16_t version_max;
839 uint16_t suites_buf[BR_MAX_CIPHER_SUITES];
840 unsigned char suites_num;
841
842 /*
843 * For clients, the server name to send as a SNI extension. For
844 * servers, the name received in the SNI extension (if any).
845 */
846 char server_name[256];
847
848 /*
849 * "Security parameters". These are filled by the handshake
850 * handler, and used when switching encryption state.
851 */
852 unsigned char client_random[32];
853 unsigned char server_random[32];
854 br_ssl_session_parameters session;
855
856 /*
857 * ECDHE elements: curve and point from the peer. The server also
858 * uses that buffer for the point to send to the client.
859 */
860 unsigned char ecdhe_curve;
861 unsigned char ecdhe_point[133];
862 unsigned char ecdhe_point_len;
863
864 /*
865 * Secure renegotiation (RFC 5746): 'reneg' can be:
866 * 0 first handshake (server support is not known)
867 * 1 server does not support secure renegotiation
868 * 2 server supports secure renegotiation
869 *
870 * The saved_finished buffer contains the client and the
871 * server "Finished" values from the last handshake, in
872 * that order (12 bytes each).
873 */
874 unsigned char reneg;
875 unsigned char saved_finished[24];
876
877 /*
878 * Behavioural flags.
879 */
880 uint32_t flags;
881
882 /*
883 * Context variables for the handshake processor. The 'pad' must
884 * be large enough to accommodate an RSA-encrypted pre-master
885 * secret, or an RSA signature; since we want to support up to
886 * RSA-4096, this means at least 512 bytes. (Other pad usages
887 * require its length to be at least 256.)
888 */
889 struct {
890 uint32_t *dp;
891 uint32_t *rp;
892 const unsigned char *ip;
893 } cpu;
894 uint32_t dp_stack[32];
895 uint32_t rp_stack[32];
896 unsigned char pad[512];
897 unsigned char *hbuf_in, *hbuf_out, *saved_hbuf_out;
898 size_t hlen_in, hlen_out;
899 void (*hsrun)(void *ctx);
900
901 /*
902 * The 'action' value communicates OOB information between the
903 * engine and the handshake processor.
904 *
905 * From the engine:
906 * 0 invocation triggered by I/O
907 * 1 invocation triggered by explicit close
908 * 2 invocation triggered by explicit renegotiation
909 */
910 unsigned char action;
911
912 /*
913 * State for alert messages. Value is either 0, or the value of
914 * the alert level byte (level is either 1 for warning, or 2 for
915 * fatal; we convert all other values to 'fatal').
916 */
917 unsigned char alert;
918
919 /*
920 * Closure flags. This flag is set when a close_notify has been
921 * received from the peer.
922 */
923 unsigned char close_received;
924
925 /*
926 * Multi-hasher for the handshake messages. The handshake handler
927 * is responsible for resetting it when appropriate.
928 */
929 br_multihash_context mhash;
930
931 /*
932 * Pointer to the X.509 engine. The engine is supposed to be
933 * already initialized. It is used to validate the peer's
934 * certificate.
935 */
936 const br_x509_class **x509ctx;
937
938 /*
939 * Certificate chain to send. This is used by both client and
940 * server, when they send their respective Certificate messages.
941 * If chain_len is 0, then chain may be NULL.
942 */
943 const br_x509_certificate *chain;
944 size_t chain_len;
945 const unsigned char *cert_cur;
946 size_t cert_len;
947
948 /*
949 * Pointers to implementations; left to NULL for unsupported
950 * functions. For the raw hash functions, implementations are
951 * referenced from the multihasher (mhash field).
952 */
953 br_tls_prf_impl prf10;
954 br_tls_prf_impl prf_sha256;
955 br_tls_prf_impl prf_sha384;
956 const br_block_cbcenc_class *iaes_cbcenc;
957 const br_block_cbcdec_class *iaes_cbcdec;
958 const br_block_ctr_class *iaes_ctr;
959 const br_block_cbcenc_class *ides_cbcenc;
960 const br_block_cbcdec_class *ides_cbcdec;
961 br_ghash ighash;
962 br_chacha20_run ichacha;
963 br_poly1305_run ipoly;
964 const br_sslrec_in_cbc_class *icbc_in;
965 const br_sslrec_out_cbc_class *icbc_out;
966 const br_sslrec_in_gcm_class *igcm_in;
967 const br_sslrec_out_gcm_class *igcm_out;
968 const br_sslrec_in_chapol_class *ichapol_in;
969 const br_sslrec_out_chapol_class *ichapol_out;
970 const br_ec_impl *iec;
971 br_rsa_pkcs1_vrfy irsavrfy;
972 br_ecdsa_vrfy iecdsa;
973 #endif
974 } br_ssl_engine_context;
975
976 /**
977 * \brief Get currently defined engine behavioural flags.
978 *
979 * \param cc SSL engine context.
980 * \return the flags.
981 */
982 static inline uint32_t
983 br_ssl_engine_get_flags(br_ssl_engine_context *cc)
984 {
985 return cc->flags;
986 }
987
988 /**
989 * \brief Set all engine behavioural flags.
990 *
991 * \param cc SSL engine context.
992 * \param flags new value for all flags.
993 */
994 static inline void
995 br_ssl_engine_set_all_flags(br_ssl_engine_context *cc, uint32_t flags)
996 {
997 cc->flags = flags;
998 }
999
1000 /**
1001 * \brief Set some engine behavioural flags.
1002 *
1003 * The flags set in the `flags` parameter are set in the context; other
1004 * flags are untouched.
1005 *
1006 * \param cc SSL engine context.
1007 * \param flags additional set flags.
1008 */
1009 static inline void
1010 br_ssl_engine_add_flags(br_ssl_engine_context *cc, uint32_t flags)
1011 {
1012 cc->flags |= flags;
1013 }
1014
1015 /**
1016 * \brief Clear some engine behavioural flags.
1017 *
1018 * The flags set in the `flags` parameter are cleared from the context; other
1019 * flags are untouched.
1020 *
1021 * \param cc SSL engine context.
1022 * \param flags flags to remove.
1023 */
1024 static inline void
1025 br_ssl_engine_remove_flags(br_ssl_engine_context *cc, uint32_t flags)
1026 {
1027 cc->flags &= ~flags;
1028 }
1029
1030 /**
1031 * \brief Behavioural flag: enforce server preferences.
1032 *
1033 * If this flag is set, then the server will enforce its own cipher suite
1034 * preference order; otherwise, it follows the client preferences.
1035 */
1036 #define BR_OPT_ENFORCE_SERVER_PREFERENCES ((uint32_t)1 << 0)
1037
1038 /**
1039 * \brief Behavioural flag: disable renegotiation.
1040 *
1041 * If this flag is set, then renegotiations are rejected unconditionally:
1042 * they won't be honoured if asked for programmatically, and requests from
1043 * the peer are rejected.
1044 */
1045 #define BR_OPT_NO_RENEGOTIATION ((uint32_t)1 << 1)
1046
1047 /**
1048 * \brief Behavioural flag: tolerate lack of client authentication.
1049 *
1050 * If this flag is set in a server and the server requests a client
1051 * certificate, but the authentication fails (the client does not send
1052 * a certificate, or the client's certificate chain cannot be validated),
1053 * then the connection keeps on. Without this flag, a failed client
1054 * authentication terminates the connection.
1055 *
1056 * Notes:
1057 *
1058 * - If the client's certificate can be validated and its public key is
1059 * supported, then a wrong signature value terminates the connection
1060 * regardless of that flag.
1061 *
1062 * - If using full-static ECDH, then a failure to validate the client's
1063 * certificate prevents the handshake from succeeding.
1064 */
1065 #define BR_OPT_TOLERATE_NO_CLIENT_AUTH ((uint32_t)1 << 2)
1066
1067 /**
1068 * \brief Set the minimum and maximum supported protocol versions.
1069 *
1070 * The two provided versions MUST be supported by the implementation
1071 * (i.e. TLS 1.0, 1.1 and 1.2), and `version_max` MUST NOT be lower
1072 * than `version_min`.
1073 *
1074 * \param cc SSL engine context.
1075 * \param version_min minimum supported TLS version.
1076 * \param version_max maximum supported TLS version.
1077 */
1078 static inline void
1079 br_ssl_engine_set_versions(br_ssl_engine_context *cc,
1080 unsigned version_min, unsigned version_max)
1081 {
1082 cc->version_min = version_min;
1083 cc->version_max = version_max;
1084 }
1085
1086 /**
1087 * \brief Set the list of cipher suites advertised by this context.
1088 *
1089 * The provided array is copied into the context. It is the caller
1090 * responsibility to ensure that all provided suites will be supported
1091 * by the context. The engine context has enough room to receive _all_
1092 * suites supported by the implementation. The provided array MUST NOT
1093 * contain duplicates.
1094 *
1095 * If the engine is for a client, the "signaling" pseudo-cipher suite
1096 * `TLS_FALLBACK_SCSV` can be added at the end of the list, if the
1097 * calling application is performing a voluntary downgrade (voluntary
1098 * downgrades are not recommended, but if such a downgrade is done, then
1099 * adding the fallback pseudo-suite is a good idea).
1100 *
1101 * \param cc SSL engine context.
1102 * \param suites cipher suites.
1103 * \param suites_num number of cipher suites.
1104 */
1105 void br_ssl_engine_set_suites(br_ssl_engine_context *cc,
1106 const uint16_t *suites, size_t suites_num);
1107
1108 /**
1109 * \brief Set the X.509 engine.
1110 *
1111 * The caller shall ensure that the X.509 engine is properly initialised.
1112 *
1113 * \param cc SSL engine context.
1114 * \param x509ctx X.509 certificate validation context.
1115 */
1116 static inline void
1117 br_ssl_engine_set_x509(br_ssl_engine_context *cc, const br_x509_class **x509ctx)
1118 {
1119 cc->x509ctx = x509ctx;
1120 }
1121
1122 /**
1123 * \brief Set a hash function implementation (by ID).
1124 *
1125 * Hash functions set with this call will be used for SSL/TLS specific
1126 * usages, not X.509 certificate validation. Only "standard" hash functions
1127 * may be set (MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512). If `impl`
1128 * is `NULL`, then the hash function support is removed, not added.
1129 *
1130 * \param ctx SSL engine context.
1131 * \param id hash function identifier.
1132 * \param impl hash function implementation (or `NULL`).
1133 */
1134 static inline void
1135 br_ssl_engine_set_hash(br_ssl_engine_context *ctx,
1136 int id, const br_hash_class *impl)
1137 {
1138 br_multihash_setimpl(&ctx->mhash, id, impl);
1139 }
1140
1141 /**
1142 * \brief Get a hash function implementation (by ID).
1143 *
1144 * This function retrieves a hash function implementation which was
1145 * set with `br_ssl_engine_set_hash()`.
1146 *
1147 * \param ctx SSL engine context.
1148 * \param id hash function identifier.
1149 * \return the hash function implementation (or `NULL`).
1150 */
1151 static inline const br_hash_class *
1152 br_ssl_engine_get_hash(br_ssl_engine_context *ctx, int id)
1153 {
1154 return br_multihash_getimpl(&ctx->mhash, id);
1155 }
1156
1157 /**
1158 * \brief Set the PRF implementation (for TLS 1.0 and 1.1).
1159 *
1160 * This function sets (or removes, if `impl` is `NULL`) the implemenation
1161 * for the PRF used in TLS 1.0 and 1.1.
1162 *
1163 * \param cc SSL engine context.
1164 * \param impl PRF implementation (or `NULL`).
1165 */
1166 static inline void
1167 br_ssl_engine_set_prf10(br_ssl_engine_context *cc, br_tls_prf_impl impl)
1168 {
1169 cc->prf10 = impl;
1170 }
1171
1172 /**
1173 * \brief Set the PRF implementation with SHA-256 (for TLS 1.2).
1174 *
1175 * This function sets (or removes, if `impl` is `NULL`) the implemenation
1176 * for the SHA-256 variant of the PRF used in TLS 1.2.
1177 *
1178 * \param cc SSL engine context.
1179 * \param impl PRF implementation (or `NULL`).
1180 */
1181 static inline void
1182 br_ssl_engine_set_prf_sha256(br_ssl_engine_context *cc, br_tls_prf_impl impl)
1183 {
1184 cc->prf_sha256 = impl;
1185 }
1186
1187 /**
1188 * \brief Set the PRF implementation with SHA-384 (for TLS 1.2).
1189 *
1190 * This function sets (or removes, if `impl` is `NULL`) the implemenation
1191 * for the SHA-384 variant of the PRF used in TLS 1.2.
1192 *
1193 * \param cc SSL engine context.
1194 * \param impl PRF implementation (or `NULL`).
1195 */
1196 static inline void
1197 br_ssl_engine_set_prf_sha384(br_ssl_engine_context *cc, br_tls_prf_impl impl)
1198 {
1199 cc->prf_sha384 = impl;
1200 }
1201
1202 /**
1203 * \brief Set the AES/CBC implementations.
1204 *
1205 * \param cc SSL engine context.
1206 * \param impl_enc AES/CBC encryption implementation (or `NULL`).
1207 * \param impl_dec AES/CBC decryption implementation (or `NULL`).
1208 */
1209 static inline void
1210 br_ssl_engine_set_aes_cbc(br_ssl_engine_context *cc,
1211 const br_block_cbcenc_class *impl_enc,
1212 const br_block_cbcdec_class *impl_dec)
1213 {
1214 cc->iaes_cbcenc = impl_enc;
1215 cc->iaes_cbcdec = impl_dec;
1216 }
1217
1218 /**
1219 * \brief Set the AES/CTR implementation.
1220 *
1221 * \param cc SSL engine context.
1222 * \param impl AES/CTR encryption/decryption implementation (or `NULL`).
1223 */
1224 static inline void
1225 br_ssl_engine_set_aes_ctr(br_ssl_engine_context *cc,
1226 const br_block_ctr_class *impl)
1227 {
1228 cc->iaes_ctr = impl;
1229 }
1230
1231 /**
1232 * \brief Set the DES/CBC implementations.
1233 *
1234 * \param cc SSL engine context.
1235 * \param impl_enc DES/CBC encryption implementation (or `NULL`).
1236 * \param impl_dec DES/CBC decryption implementation (or `NULL`).
1237 */
1238 static inline void
1239 br_ssl_engine_set_des_cbc(br_ssl_engine_context *cc,
1240 const br_block_cbcenc_class *impl_enc,
1241 const br_block_cbcdec_class *impl_dec)
1242 {
1243 cc->ides_cbcenc = impl_enc;
1244 cc->ides_cbcdec = impl_dec;
1245 }
1246
1247 /**
1248 * \brief Set the GHASH implementation (used in GCM mode).
1249 *
1250 * \param cc SSL engine context.
1251 * \param impl GHASH implementation (or `NULL`).
1252 */
1253 static inline void
1254 br_ssl_engine_set_ghash(br_ssl_engine_context *cc, br_ghash impl)
1255 {
1256 cc->ighash = impl;
1257 }
1258
1259 /**
1260 * \brief Set the ChaCha20 implementation.
1261 *
1262 * \param cc SSL engine context.
1263 * \param ichacha ChaCha20 implementation (or `NULL`).
1264 */
1265 static inline void
1266 br_ssl_engine_set_chacha20(br_ssl_engine_context *cc,
1267 br_chacha20_run ichacha)
1268 {
1269 cc->ichacha = ichacha;
1270 }
1271
1272 /**
1273 * \brief Set the Poly1305 implementation.
1274 *
1275 * \param cc SSL engine context.
1276 * \param ipoly Poly1305 implementation (or `NULL`).
1277 */
1278 static inline void
1279 br_ssl_engine_set_poly1305(br_ssl_engine_context *cc,
1280 br_poly1305_run ipoly)
1281 {
1282 cc->ipoly = ipoly;
1283 }
1284
1285 /**
1286 * \brief Set the record encryption and decryption engines for CBC + HMAC.
1287 *
1288 * \param cc SSL engine context.
1289 * \param impl_in record CBC decryption implementation (or `NULL`).
1290 * \param impl_out record CBC encryption implementation (or `NULL`).
1291 */
1292 static inline void
1293 br_ssl_engine_set_cbc(br_ssl_engine_context *cc,
1294 const br_sslrec_in_cbc_class *impl_in,
1295 const br_sslrec_out_cbc_class *impl_out)
1296 {
1297 cc->icbc_in = impl_in;
1298 cc->icbc_out = impl_out;
1299 }
1300
1301 /**
1302 * \brief Set the record encryption and decryption engines for GCM.
1303 *
1304 * \param cc SSL engine context.
1305 * \param impl_in record GCM decryption implementation (or `NULL`).
1306 * \param impl_out record GCM encryption implementation (or `NULL`).
1307 */
1308 static inline void
1309 br_ssl_engine_set_gcm(br_ssl_engine_context *cc,
1310 const br_sslrec_in_gcm_class *impl_in,
1311 const br_sslrec_out_gcm_class *impl_out)
1312 {
1313 cc->igcm_in = impl_in;
1314 cc->igcm_out = impl_out;
1315 }
1316
1317 /**
1318 * \brief Set the record encryption and decryption engines for
1319 * ChaCha20+Poly1305.
1320 *
1321 * \param cc SSL engine context.
1322 * \param impl_in record ChaCha20 decryption implementation (or `NULL`).
1323 * \param impl_out record ChaCha20 encryption implementation (or `NULL`).
1324 */
1325 static inline void
1326 br_ssl_engine_set_chapol(br_ssl_engine_context *cc,
1327 const br_sslrec_in_chapol_class *impl_in,
1328 const br_sslrec_out_chapol_class *impl_out)
1329 {
1330 cc->ichapol_in = impl_in;
1331 cc->ichapol_out = impl_out;
1332 }
1333
1334 /**
1335 * \brief Set the EC implementation.
1336 *
1337 * The elliptic curve implementation will be used for ECDH and ECDHE
1338 * cipher suites, and for ECDSA support.
1339 *
1340 * \param cc SSL engine context.
1341 * \param iec EC implementation (or `NULL`).
1342 */
1343 static inline void
1344 br_ssl_engine_set_ec(br_ssl_engine_context *cc, const br_ec_impl *iec)
1345 {
1346 cc->iec = iec;
1347 }
1348
1349 /**
1350 * \brief Set the RSA signature verification implementation.
1351 *
1352 * On the client, this is used to verify the server's signature on its
1353 * ServerKeyExchange message (for ECDHE_RSA cipher suites). On the server,
1354 * this is used to verify the client's CertificateVerify message (if a
1355 * client certificate is requested, and that certificate contains a RSA key).
1356 *
1357 * \param cc SSL engine context.
1358 * \param irsavrfy RSA signature verification implementation.
1359 */
1360 static inline void
1361 br_ssl_engine_set_rsavrfy(br_ssl_engine_context *cc, br_rsa_pkcs1_vrfy irsavrfy)
1362 {
1363 cc->irsavrfy = irsavrfy;
1364 }
1365
1366 /*
1367 * \brief Set the ECDSA implementation (signature verification).
1368 *
1369 * On the client, this is used to verify the server's signature on its
1370 * ServerKeyExchange message (for ECDHE_ECDSA cipher suites). On the server,
1371 * this is used to verify the client's CertificateVerify message (if a
1372 * client certificate is requested, that certificate contains an EC key,
1373 * and full-static ECDH is not used).
1374 *
1375 * The ECDSA implementation will use the EC core implementation configured
1376 * in the engine context.
1377 *
1378 * \param cc client context.
1379 * \param iecdsa ECDSA verification implementation.
1380 */
1381 static inline void
1382 br_ssl_engine_set_ecdsa(br_ssl_engine_context *cc, br_ecdsa_vrfy iecdsa)
1383 {
1384 cc->iecdsa = iecdsa;
1385 }
1386
1387 /**
1388 * \brief Set the I/O buffer for the SSL engine.
1389 *
1390 * Once this call has been made, `br_ssl_client_reset()` or
1391 * `br_ssl_server_reset()` MUST be called before using the context.
1392 *
1393 * The provided buffer will be used as long as the engine context is
1394 * used. The caller is responsible for keeping it available.
1395 *
1396 * If `bidi` is 0, then the engine will operate in half-duplex mode
1397 * (it won't be able to send data while there is unprocessed incoming
1398 * data in the buffer, and it won't be able to receive data while there
1399 * is unsent data in the buffer). The optimal buffer size in half-duplex
1400 * mode is `BR_SSL_BUFSIZE_MONO`; if the buffer is larger, then extra
1401 * bytes are ignored. If the buffer is smaller, then this limits the
1402 * capacity of the engine to support all allowed record sizes.
1403 *
1404 * If `bidi` is 1, then the engine will split the buffer into two
1405 * parts, for separate handling of outgoing and incoming data. This
1406 * enables full-duplex processing, but requires more RAM. The optimal
1407 * buffer size in full-duplex mode is `BR_SSL_BUFSIZE_BIDI`; if the
1408 * buffer is larger, then extra bytes are ignored. If the buffer is
1409 * smaller, then the split will favour the incoming part, so that
1410 * interoperability is maximised.
1411 *
1412 * \param cc SSL engine context
1413 * \param iobuf I/O buffer.
1414 * \param iobuf_len I/O buffer length (in bytes).
1415 * \param bidi non-zero for full-duplex mode.
1416 */
1417 void br_ssl_engine_set_buffer(br_ssl_engine_context *cc,
1418 void *iobuf, size_t iobuf_len, int bidi);
1419
1420 /**
1421 * \brief Set the I/O buffers for the SSL engine.
1422 *
1423 * Once this call has been made, `br_ssl_client_reset()` or
1424 * `br_ssl_server_reset()` MUST be called before using the context.
1425 *
1426 * This function is similar to `br_ssl_engine_set_buffer()`, except
1427 * that it enforces full-duplex mode, and the two I/O buffers are
1428 * provided as separate chunks.
1429 *
1430 * The macros `BR_SSL_BUFSIZE_INPUT` and `BR_SSL_BUFSIZE_OUTPUT`
1431 * evaluate to the optimal (maximum) sizes for the input and output
1432 * buffer, respectively.
1433 *
1434 * \param cc SSL engine context
1435 * \param ibuf input buffer.
1436 * \param ibuf_len input buffer length (in bytes).
1437 * \param obuf output buffer.
1438 * \param obuf_len output buffer length (in bytes).
1439 */
1440 void br_ssl_engine_set_buffers_bidi(br_ssl_engine_context *cc,
1441 void *ibuf, size_t ibuf_len, void *obuf, size_t obuf_len);
1442
1443 /**
1444 * \brief Inject some "initial entropy" in the context.
1445 *
1446 * This entropy will be added to what can be obtained from the
1447 * underlying operating system, if that OS is supported.
1448 *
1449 * This function may be called several times; all injected entropy chunks
1450 * are cumulatively mixed.
1451 *
1452 * If entropy gathering from the OS is supported and compiled in, then this
1453 * step is optional. Otherwise, it is mandatory to inject randomness, and
1454 * the caller MUST take care to push (as one or several successive calls)
1455 * enough entropy to achieve cryptographic resistance (at least 80 bits,
1456 * preferably 128 or more). The engine will report an error if no entropy
1457 * was provided and none can be obtained from the OS.
1458 *
1459 * Take care that this function cannot assess the cryptographic quality of
1460 * the provided bytes.
1461 *
1462 * In all generality, "entropy" must here be considered to mean "that
1463 * which the attacker cannot predict". If your OS/architecture does not
1464 * have a suitable source of randomness, then you can make do with the
1465 * combination of a large enough secret value (possibly a copy of an
1466 * asymmetric private key that you also store on the system) AND a
1467 * non-repeating value (e.g. current time, provided that the local clock
1468 * cannot be reset or altered by the attacker).
1469 *
1470 * \param cc SSL engine context.
1471 * \param data extra entropy to inject.
1472 * \param len length of the extra data (in bytes).
1473 */
1474 void br_ssl_engine_inject_entropy(br_ssl_engine_context *cc,
1475 const void *data, size_t len);
1476
1477 /**
1478 * \brief Get the "server name" in this engine.
1479 *
1480 * For clients, this is the name provided with `br_ssl_client_reset()`;
1481 * for servers, this is the name received from the client as part of the
1482 * ClientHello message. If there is no such name (e.g. the client did
1483 * not send an SNI extension) then the returned string is empty
1484 * (returned pointer points to a byte of value 0).
1485 *
1486 * The returned pointer refers to a buffer inside the context, which may
1487 * be overwritten as part of normal SSL activity (even within the same
1488 * connection, if a renegotiation occurs).
1489 *
1490 * \param cc SSL engine context.
1491 * \return the server name (possibly empty).
1492 */
1493 static inline const char *
1494 br_ssl_engine_get_server_name(const br_ssl_engine_context *cc)
1495 {
1496 return cc->server_name;
1497 }
1498
1499 /**
1500 * \brief Get the protocol version.
1501 *
1502 * This function returns the protocol version that is used by the
1503 * engine. That value is set after sending (for a server) or receiving
1504 * (for a client) the ServerHello message.
1505 *
1506 * \param cc SSL engine context.
1507 * \return the protocol version.
1508 */
1509 static inline unsigned
1510 br_ssl_engine_get_version(const br_ssl_engine_context *cc)
1511 {
1512 return cc->session.version;
1513 }
1514
1515 /**
1516 * \brief Get a copy of the session parameters.
1517 *
1518 * The session parameters are filled during the handshake, so this
1519 * function shall not be called before completion of the handshake.
1520 * The initial handshake is completed when the context first allows
1521 * application data to be injected.
1522 *
1523 * This function copies the current session parameters into the provided
1524 * structure. Beware that the session parameters include the master
1525 * secret, which is sensitive data, to handle with great care.
1526 *
1527 * \param cc SSL engine context.
1528 * \param pp destination structure for the session parameters.
1529 */
1530 static inline void
1531 br_ssl_engine_get_session_parameters(const br_ssl_engine_context *cc,
1532 br_ssl_session_parameters *pp)
1533 {
1534 memcpy(pp, &cc->session, sizeof *pp);
1535 }
1536
1537 /**
1538 * \brief Set the session parameters to the provided values.
1539 *
1540 * This function is meant to be used in the client, before doing a new
1541 * handshake; a session resumption will be attempted with these
1542 * parameters. In the server, this function has no effect.
1543 *
1544 * \param cc SSL engine context.
1545 * \param pp source structure for the session parameters.
1546 */
1547 static inline void
1548 br_ssl_engine_set_session_parameters(br_ssl_engine_context *cc,
1549 const br_ssl_session_parameters *pp)
1550 {
1551 memcpy(&cc->session, pp, sizeof *pp);
1552 }
1553
1554 /**
1555 * \brief Get the current engine state.
1556 *
1557 * An SSL engine (client or server) has, at any time, a state which is
1558 * the combination of zero, one or more of these flags:
1559 *
1560 * - `BR_SSL_CLOSED`
1561 *
1562 * Engine is finished, no more I/O (until next reset).
1563 *
1564 * - `BR_SSL_SENDREC`
1565 *
1566 * Engine has some bytes to send to the peer.
1567 *
1568 * - `BR_SSL_RECVREC`
1569 *
1570 * Engine expects some bytes from the peer.
1571 *
1572 * - `BR_SSL_SENDAPP`
1573 *
1574 * Engine may receive application data to send (or flush).
1575 *
1576 * - `BR_SSL_RECVAPP`
1577 *
1578 * Engine has obtained some application data from the peer,
1579 * that should be read by the caller.
1580 *
1581 * If no flag at all is set (state value is 0), then the engine is not
1582 * fully initialised yet.
1583 *
1584 * The `BR_SSL_CLOSED` flag is exclusive; when it is set, no other flag
1585 * is set. To distinguish between a normal closure and an error, use
1586 * `br_ssl_engine_last_error()`.
1587 *
1588 * Generally speaking, `BR_SSL_SENDREC` and `BR_SSL_SENDAPP` are mutually
1589 * exclusive: the input buffer, at any point, either accumulates
1590 * plaintext data, or contains an assembled record that is being sent.
1591 * Similarly, `BR_SSL_RECVREC` and `BR_SSL_RECVAPP` are mutually exclusive.
1592 * This may change in a future library version.
1593 *
1594 * \param cc SSL engine context.
1595 * \return the current engine state.
1596 */
1597 unsigned br_ssl_engine_current_state(const br_ssl_engine_context *cc);
1598
1599 /** \brief SSL engine state: closed or failed. */
1600 #define BR_SSL_CLOSED 0x0001
1601 /** \brief SSL engine state: record data is ready to be sent to the peer. */
1602 #define BR_SSL_SENDREC 0x0002
1603 /** \brief SSL engine state: engine may receive records from the peer. */
1604 #define BR_SSL_RECVREC 0x0004
1605 /** \brief SSL engine state: engine may accept application data to send. */
1606 #define BR_SSL_SENDAPP 0x0008
1607 /** \brief SSL engine state: engine has received application data. */
1608 #define BR_SSL_RECVAPP 0x0010
1609
1610 /**
1611 * \brief Get the engine error indicator.
1612 *
1613 * The error indicator is `BR_ERR_OK` (0) if no error was encountered
1614 * since the last call to `br_ssl_client_reset()` or
1615 * `br_ssl_server_reset()`. Other status values are "sticky": they
1616 * remain set, and prevent all I/O activity, until cleared. Only the
1617 * reset calls clear the error indicator.
1618 *
1619 * \param cc SSL engine context.
1620 * \return 0, or a non-zero error code.
1621 */
1622 static inline int
1623 br_ssl_engine_last_error(const br_ssl_engine_context *cc)
1624 {
1625 return cc->err;
1626 }
1627
1628 /*
1629 * There are four I/O operations, each identified by a symbolic name:
1630 *
1631 * sendapp inject application data in the engine
1632 * recvapp retrieving application data from the engine
1633 * sendrec sending records on the transport medium
1634 * recvrec receiving records from the transport medium
1635 *
1636 * Terminology works thus: in a layered model where the SSL engine sits
1637 * between the application and the network, "send" designates operations
1638 * where bytes flow from application to network, and "recv" for the
1639 * reverse operation. Application data (the plaintext that is to be
1640 * conveyed through SSL) is "app", while encrypted records are "rec".
1641 * Note that from the SSL engine point of view, "sendapp" and "recvrec"
1642 * designate bytes that enter the engine ("inject" operation), while
1643 * "recvapp" and "sendrec" designate bytes that exit the engine
1644 * ("extract" operation).
1645 *
1646 * For the operation 'xxx', two functions are defined:
1647 *
1648 * br_ssl_engine_xxx_buf
1649 * Returns a pointer and length to the buffer to use for that
1650 * operation. '*len' is set to the number of bytes that may be read
1651 * from the buffer (extract operation) or written to the buffer
1652 * (inject operation). If no byte may be exchanged for that operation
1653 * at that point, then '*len' is set to zero, and NULL is returned.
1654 * The engine state is unmodified by this call.
1655 *
1656 * br_ssl_engine_xxx_ack
1657 * Informs the engine that 'len' bytes have been read from the buffer
1658 * (extract operation) or written to the buffer (inject operation).
1659 * The 'len' value MUST NOT be zero. The 'len' value MUST NOT exceed
1660 * that which was obtained from a preceeding br_ssl_engine_xxx_buf()
1661 * call.
1662 */
1663
1664 /**
1665 * \brief Get buffer for application data to send.
1666 *
1667 * If the engine is ready to accept application data to send to the
1668 * peer, then this call returns a pointer to the buffer where such
1669 * data shall be written, and its length is written in `*len`.
1670 * Otherwise, `*len` is set to 0 and `NULL` is returned.
1671 *
1672 * \param cc SSL engine context.
1673 * \param len receives the application data output buffer length, or 0.
1674 * \return the application data output buffer, or `NULL`.
1675 */
1676 unsigned char *br_ssl_engine_sendapp_buf(
1677 const br_ssl_engine_context *cc, size_t *len);
1678
1679 /**
1680 * \brief Inform the engine of some new application data.
1681 *
1682 * After writing `len` bytes in the buffer returned by
1683 * `br_ssl_engine_sendapp_buf()`, the application shall call this
1684 * function to trigger any relevant processing. The `len` parameter
1685 * MUST NOT be 0, and MUST NOT exceed the value obtained in the
1686 * `br_ssl_engine_sendapp_buf()` call.
1687 *
1688 * \param cc SSL engine context.
1689 * \param len number of bytes pushed (not zero).
1690 */
1691 void br_ssl_engine_sendapp_ack(br_ssl_engine_context *cc, size_t len);
1692
1693 /**
1694 * \brief Get buffer for received application data.
1695 *
1696 * If the engine has received application data from the peer, hen this
1697 * call returns a pointer to the buffer from where such data shall be
1698 * read, and its length is written in `*len`. Otherwise, `*len` is set
1699 * to 0 and `NULL` is returned.
1700 *
1701 * \param cc SSL engine context.
1702 * \param len receives the application data input buffer length, or 0.
1703 * \return the application data input buffer, or `NULL`.
1704 */
1705 unsigned char *br_ssl_engine_recvapp_buf(
1706 const br_ssl_engine_context *cc, size_t *len);
1707
1708 /**
1709 * \brief Acknowledge some received application data.
1710 *
1711 * After reading `len` bytes from the buffer returned by
1712 * `br_ssl_engine_recvapp_buf()`, the application shall call this
1713 * function to trigger any relevant processing. The `len` parameter
1714 * MUST NOT be 0, and MUST NOT exceed the value obtained in the
1715 * `br_ssl_engine_recvapp_buf()` call.
1716 *
1717 * \param cc SSL engine context.
1718 * \param len number of bytes read (not zero).
1719 */
1720 void br_ssl_engine_recvapp_ack(br_ssl_engine_context *cc, size_t len);
1721
1722 /**
1723 * \brief Get buffer for record data to send.
1724 *
1725 * If the engine has prepared some records to send to the peer, then this
1726 * call returns a pointer to the buffer from where such data shall be
1727 * read, and its length is written in `*len`. Otherwise, `*len` is set
1728 * to 0 and `NULL` is returned.
1729 *
1730 * \param cc SSL engine context.
1731 * \param len receives the record data output buffer length, or 0.
1732 * \return the record data output buffer, or `NULL`.
1733 */
1734 unsigned char *br_ssl_engine_sendrec_buf(
1735 const br_ssl_engine_context *cc, size_t *len);
1736
1737 /**
1738 * \brief Acknowledge some sent record data.
1739 *
1740 * After reading `len` bytes from the buffer returned by
1741 * `br_ssl_engine_sendrec_buf()`, the application shall call this
1742 * function to trigger any relevant processing. The `len` parameter
1743 * MUST NOT be 0, and MUST NOT exceed the value obtained in the
1744 * `br_ssl_engine_sendrec_buf()` call.
1745 *
1746 * \param cc SSL engine context.
1747 * \param len number of bytes read (not zero).
1748 */
1749 void br_ssl_engine_sendrec_ack(br_ssl_engine_context *cc, size_t len);
1750
1751 /**
1752 * \brief Get buffer for incoming records.
1753 *
1754 * If the engine is ready to accept records from the peer, then this
1755 * call returns a pointer to the buffer where such data shall be
1756 * written, and its length is written in `*len`. Otherwise, `*len` is
1757 * set to 0 and `NULL` is returned.
1758 *
1759 * \param cc SSL engine context.
1760 * \param len receives the record data input buffer length, or 0.
1761 * \return the record data input buffer, or `NULL`.
1762 */
1763 unsigned char *br_ssl_engine_recvrec_buf(
1764 const br_ssl_engine_context *cc, size_t *len);
1765
1766 /**
1767 * \brief Inform the engine of some new record data.
1768 *
1769 * After writing `len` bytes in the buffer returned by
1770 * `br_ssl_engine_recvrec_buf()`, the application shall call this
1771 * function to trigger any relevant processing. The `len` parameter
1772 * MUST NOT be 0, and MUST NOT exceed the value obtained in the
1773 * `br_ssl_engine_recvrec_buf()` call.
1774 *
1775 * \param cc SSL engine context.
1776 * \param len number of bytes pushed (not zero).
1777 */
1778 void br_ssl_engine_recvrec_ack(br_ssl_engine_context *cc, size_t len);
1779
1780 /**
1781 * \brief Flush buffered application data.
1782 *
1783 * If some application data has been buffered in the engine, then wrap
1784 * it into a record and mark it for sending. If no application data has
1785 * been buffered but the engine would be ready to accept some, AND the
1786 * `force` parameter is non-zero, then an empty record is assembled and
1787 * marked for sending. In all other cases, this function does nothing.
1788 *
1789 * Empty records are technically legal, but not all existing SSL/TLS
1790 * implementations support them. Empty records can be useful as a
1791 * transparent "keep-alive" mechanism to maintain some low-level
1792 * network activity.
1793 *
1794 * \param cc SSL engine context.
1795 * \param force non-zero to force sending an empty record.
1796 */
1797 void br_ssl_engine_flush(br_ssl_engine_context *cc, int force);
1798
1799 /**
1800 * \brief Initiate a closure.
1801 *
1802 * If, at that point, the context is open and in ready state, then a
1803 * `close_notify` alert is assembled and marked for sending; this
1804 * triggers the closure protocol. Otherwise, no such alert is assembled.
1805 *
1806 * \param cc SSL engine context.
1807 */
1808 void br_ssl_engine_close(br_ssl_engine_context *cc);
1809
1810 /**
1811 * \brief Initiate a renegotiation.
1812 *
1813 * If the engine is failed or closed, or if the peer is known not to
1814 * support secure renegotiation (RFC 5746), or if renegotiations have
1815 * been disabled with the `BR_OPT_NO_RENEGOTIATION` flag, then this
1816 * function returns 0 and nothing else happens.
1817 *
1818 * Otherwise, this function returns 1, and a renegotiation attempt is
1819 * triggered (if a handshake is already ongoing at that point, then
1820 * no new handshake is triggered).
1821 *
1822 * \param cc SSL engine context.
1823 * \return 1 on success, 0 on error.
1824 */
1825 int br_ssl_engine_renegotiate(br_ssl_engine_context *cc);
1826
1827 /*
1828 * Pre-declaration for the SSL client context.
1829 */
1830 typedef struct br_ssl_client_context_ br_ssl_client_context;
1831
1832 /**
1833 * \brief Type for the client certificate, if requested by the server.
1834 */
1835 typedef struct {
1836 /**
1837 * \brief Authentication type.
1838 *
1839 * This is either `BR_AUTH_RSA` (RSA signature), `BR_AUTH_ECDSA`
1840 * (ECDSA signature), or `BR_AUTH_ECDH` (static ECDH key exchange).
1841 */
1842 int auth_type;
1843
1844 /**
1845 * \brief Hash function for computing the CertificateVerify.
1846 *
1847 * This is the symbolic identifier for the hash function that
1848 * will be used to produce the hash of handshake messages, to
1849 * be signed into the CertificateVerify. For full static ECDH
1850 * (client and server certificates are both EC in the same
1851 * curve, and static ECDH is used), this value is set to -1.
1852 *
1853 * Take care that with TLS 1.0 and 1.1, that value MUST match
1854 * the protocol requirements: value must be 0 (MD5+SHA-1) for
1855 * a RSA signature, or 2 (SHA-1) for an ECDSA signature. Only
1856 * TLS 1.2 allows for other hash functions.
1857 */
1858 int hash_id;
1859
1860 /**
1861 * \brief Certificate chain to send to the server.
1862 *
1863 * This is an array of `br_x509_certificate` objects, each
1864 * normally containing a DER-encoded certificate. The client
1865 * code does not try to decode these elements. If there is no
1866 * chain to send to the server, then this pointer shall be
1867 * set to `NULL`.
1868 */
1869 const br_x509_certificate *chain;
1870
1871 /**
1872 * \brief Certificate chain length (number of certificates).
1873 *
1874 * If there is no chain to send to the server, then this value
1875 * shall be set to 0.
1876 */
1877 size_t chain_len;
1878
1879 } br_ssl_client_certificate;
1880
1881 /*
1882 * Note: the constants below for signatures match the TLS constants.
1883 */
1884
1885 /** \brief Client authentication type: static ECDH. */
1886 #define BR_AUTH_ECDH 0
1887 /** \brief Client authentication type: RSA signature. */
1888 #define BR_AUTH_RSA 1
1889 /** \brief Client authentication type: ECDSA signature. */
1890 #define BR_AUTH_ECDSA 3
1891
1892 /**
1893 * \brief Class type for a certificate handler (client side).
1894 *
1895 * A certificate handler selects a client certificate chain to send to
1896 * the server, upon explicit request from that server. It receives
1897 * the list of trust anchor DN from the server, and supported types
1898 * of certificates and signatures, and returns the chain to use. It
1899 * is also invoked to perform the corresponding private key operation
1900 * (a signature, or an ECDH computation).
1901 *
1902 * The SSL client engine will first push the trust anchor DN with
1903 * `start_name_list()`, `start_name()`, `append_name()`, `end_name()`
1904 * and `end_name_list()`. Then it will call `choose()`, to select the
1905 * actual chain (and signature/hash algorithms). Finally, it will call
1906 * either `do_sign()` or `do_keyx()`, depending on the algorithm choices.
1907 */
1908 typedef struct br_ssl_client_certificate_class_ br_ssl_client_certificate_class;
1909 struct br_ssl_client_certificate_class_ {
1910 /**
1911 * \brief Context size (in bytes).
1912 */
1913 size_t context_size;
1914
1915 /**
1916 * \brief Begin reception of a list of trust anchor names. This
1917 * is called while parsing the incoming CertificateRequest.
1918 *
1919 * \param pctx certificate handler context.
1920 */
1921 void (*start_name_list)(const br_ssl_client_certificate_class **pctx);
1922
1923 /**
1924 * \brief Begin reception of a new trust anchor name.
1925 *
1926 * The total encoded name length is provided; it is less than
1927 * 65535 bytes.
1928 *
1929 * \param pctx certificate handler context.
1930 * \param len encoded name length (in bytes).
1931 */
1932 void (*start_name)(const br_ssl_client_certificate_class **pctx,
1933 size_t len);
1934
1935 /**
1936 * \brief Receive some more bytes for the current trust anchor name.
1937 *
1938 * The provided reference (`data`) points to a transient buffer
1939 * they may be reused as soon as this function returns. The chunk
1940 * length (`len`) is never zero.
1941 *
1942 * \param pctx certificate handler context.
1943 * \param data anchor name chunk.
1944 * \param len anchor name chunk length (in bytes).
1945 */
1946 void (*append_name)(const br_ssl_client_certificate_class **pctx,
1947 const unsigned char *data, size_t len);
1948
1949 /**
1950 * \brief End current trust anchor name.
1951 *
1952 * This function is called when all the encoded anchor name data
1953 * has been provided.
1954 *
1955 * \param pctx certificate handler context.
1956 */
1957 void (*end_name)(const br_ssl_client_certificate_class **pctx);
1958
1959 /**
1960 * \brief End list of trust anchor names.
1961 *
1962 * This function is called when all the anchor names in the
1963 * CertificateRequest message have been obtained.
1964 *
1965 * \param pctx certificate handler context.
1966 */
1967 void (*end_name_list)(const br_ssl_client_certificate_class **pctx);
1968
1969 /**
1970 * \brief Select client certificate and algorithms.
1971 *
1972 * This callback function shall fill the provided `choices`
1973 * structure with the selected algorithms and certificate chain.
1974 * The `hash_id`, `chain` and `chain_len` fields must be set. If
1975 * the client cannot or does not wish to send a certificate,
1976 * then it shall set `chain` to `NULL` and `chain_len` to 0.
1977 *
1978 * The `auth_types` parameter describes the authentication types,
1979 * signature algorithms and hash functions that are supported by
1980 * both the client context and the server, and compatible with
1981 * the current protocol version. This is a bit field with the
1982 * following contents:
1983 *
1984 * - If RSA signatures with hash function x are supported, then
1985 * bit x is set.
1986 *
1987 * - If ECDSA signatures with hash function x are supported,
1988 * then bit 8+x is set.
1989 *
1990 * - If static ECDH is supported, with a RSA-signed certificate,
1991 * then bit 16 is set.
1992 *
1993 * - If static ECDH is supported, with an ECDSA-signed certificate,
1994 * then bit 17 is set.
1995 *
1996 * Notes:
1997 *
1998 * - When using TLS 1.0 or 1.1, the hash function for RSA
1999 * signatures is always the special MD5+SHA-1 (id 0), and the
2000 * hash function for ECDSA signatures is always SHA-1 (id 2).
2001 *
2002 * - When using TLS 1.2, the list of hash functions is trimmed
2003 * down to include only hash functions that the client context
2004 * can support. The actual server list can be obtained with
2005 * `br_ssl_client_get_server_hashes()`; that list may be used
2006 * to select the certificate chain to send to the server.
2007 *
2008 * \param pctx certificate handler context.
2009 * \param cc SSL client context.
2010 * \param auth_types supported authentication types and algorithms.
2011 * \param choices destination structure for the policy choices.
2012 */
2013 void (*choose)(const br_ssl_client_certificate_class **pctx,
2014 const br_ssl_client_context *cc, uint32_t auth_types,
2015 br_ssl_client_certificate *choices);
2016
2017 /**
2018 * \brief Perform key exchange (client part).
2019 *
2020 * This callback is invoked in case of a full static ECDH key
2021 * exchange:
2022 *
2023 * - the cipher suite uses `ECDH_RSA` or `ECDH_ECDSA`;
2024 *
2025 * - the server requests a client certificate;
2026 *
2027 * - the client has, and sends, a client certificate that
2028 * uses an EC key in the same curve as the server's key,
2029 * and chooses static ECDH (the `hash_id` field in the choice
2030 * structure was set to -1).
2031 *
2032 * In that situation, this callback is invoked to compute the
2033 * client-side ECDH: the provided `data` (of length `len` bytes)
2034 * is the server's public key point (as decoded from its
2035 * certificate), and the client shall multiply that point with
2036 * its own private key, and write back the X coordinate of the
2037 * resulting point in the same buffer, starting at offset 1
2038 * (therefore, writing back the complete encoded point works).
2039 *
2040 * The callback must uphold the following:
2041 *
2042 * - If the input array does not have the proper length for
2043 * an encoded curve point, then an error (0) shall be reported.
2044 *
2045 * - If the input array has the proper length, then processing
2046 * MUST be constant-time, even if the data is not a valid
2047 * encoded point.
2048 *
2049 * - This callback MUST check that the input point is valid.
2050 *
2051 * Returned value is 1 on success, 0 on error.
2052 *
2053 * \param pctx certificate handler context.
2054 * \param data server public key point.
2055 * \param len server public key point length (in bytes).
2056 * \return 1 on success, 0 on error.
2057 */
2058 uint32_t (*do_keyx)(const br_ssl_client_certificate_class **pctx,
2059 unsigned char *data, size_t len);
2060
2061 /**
2062 * \brief Perform a signature (client authentication).
2063 *
2064 * This callback is invoked when a client certificate was sent,
2065 * and static ECDH is not used. It shall compute a signature,
2066 * using the client's private key, over the provided hash value
2067 * (which is the hash of all previous handshake messages).
2068 *
2069 * On input, the hash value to sign is in `data`, of size
2070 * `hv_len`; the involved hash function is identified by
2071 * `hash_id`. The signature shall be computed and written
2072 * back into `data`; the total size of that buffer is `len`
2073 * bytes.
2074 *
2075 * This callback shall verify that the signature length does not
2076 * exceed `len` bytes, and abstain from writing the signature if
2077 * it does not fit.
2078 *
2079 * For RSA signatures, the `hash_id` may be 0, in which case
2080 * this is the special header-less signature specified in TLS 1.0
2081 * and 1.1, with a 36-byte hash value. Otherwise, normal PKCS#1
2082 * v1.5 signatures shall be computed.
2083 *
2084 * For ECDSA signatures, the signature value shall use the ASN.1
2085 * based encoding.
2086 *
2087 * Returned value is the signature length (in bytes), or 0 on error.
2088 *
2089 * \param pctx certificate handler context.
2090 * \param hash_id hash function identifier.
2091 * \param hv_len hash value length (in bytes).
2092 * \param data input/output buffer (hash value, then signature).
2093 * \param len total buffer length (in bytes).
2094 * \return signature length (in bytes) on success, or 0 on error.
2095 */
2096 size_t (*do_sign)(const br_ssl_client_certificate_class **pctx,
2097 int hash_id, size_t hv_len, unsigned char *data, size_t len);
2098 };
2099
2100 /**
2101 * \brief A single-chain RSA client certificate handler.
2102 *
2103 * This handler uses a single certificate chain, with a RSA
2104 * signature. The list of trust anchor DN is ignored.
2105 *
2106 * Apart from the first field (vtable pointer), its contents are
2107 * opaque and shall not be accessed directly.
2108 */
2109 typedef struct {
2110 /** \brief Pointer to vtable. */
2111 const br_ssl_client_certificate_class *vtable;
2112 #ifndef BR_DOXYGEN_IGNORE
2113 const br_x509_certificate *chain;
2114 size_t chain_len;
2115 const br_rsa_private_key *sk;
2116 br_rsa_pkcs1_sign irsasign;
2117 #endif
2118 } br_ssl_client_certificate_rsa_context;
2119
2120 /**
2121 * \brief A single-chain EC client certificate handler.
2122 *
2123 * This handler uses a single certificate chain, with a RSA
2124 * signature. The list of trust anchor DN is ignored.
2125 *
2126 * This handler may support both static ECDH, and ECDSA signatures
2127 * (either usage may be selectively disabled).
2128 *
2129 * Apart from the first field (vtable pointer), its contents are
2130 * opaque and shall not be accessed directly.
2131 */
2132 typedef struct {
2133 /** \brief Pointer to vtable. */
2134 const br_ssl_client_certificate_class *vtable;
2135 #ifndef BR_DOXYGEN_IGNORE
2136 const br_x509_certificate *chain;
2137 size_t chain_len;
2138 const br_ec_private_key *sk;
2139 unsigned allowed_usages;
2140 unsigned issuer_key_type;
2141 const br_multihash_context *mhash;
2142 const br_ec_impl *iec;
2143 br_ecdsa_sign iecdsa;
2144 #endif
2145 } br_ssl_client_certificate_ec_context;
2146
2147 /**
2148 * \brief Context structure for a SSL client.
2149 *
2150 * The first field (called `eng`) is the SSL engine; all functions that
2151 * work on a `br_ssl_engine_context` structure shall take as parameter
2152 * a pointer to that field. The other structure fields are opaque and
2153 * must not be accessed directly.
2154 */
2155 struct br_ssl_client_context_ {
2156 /**
2157 * \brief The encapsulated engine context.
2158 */
2159 br_ssl_engine_context eng;
2160
2161 #ifndef BR_DOXYGEN_IGNORE
2162 /*
2163 * Minimum ClientHello length; padding with an extension (RFC
2164 * 7685) is added if necessary to match at least that length.
2165 * Such padding is nominally unnecessary, but it has been used
2166 * to work around some server implementation bugs.
2167 */
2168 uint16_t min_clienthello_len;
2169
2170 /*
2171 * Bit field for algoithms (hash + signature) supported by the
2172 * server when requesting a client certificate.
2173 */
2174 uint16_t hashes;
2175
2176 /*
2177 * Server's public key curve.
2178 */
2179 int server_curve;
2180
2181 /*
2182 * Context for certificate handler.
2183 */
2184 const br_ssl_client_certificate_class **client_auth_vtable;
2185
2186 /*
2187 * Client authentication type.
2188 */
2189 unsigned char auth_type;
2190
2191 /*
2192 * Hash function to use for the client signature. This is 0xFF
2193 * if static ECDH is used.
2194 */
2195 unsigned char hash_id;
2196
2197 /*
2198 * For the core certificate handlers, thus avoiding (in most
2199 * cases) the need for an externally provided policy context.
2200 */
2201 union {
2202 const br_ssl_client_certificate_class *vtable;
2203 br_ssl_client_certificate_rsa_context single_rsa;
2204 br_ssl_client_certificate_ec_context single_ec;
2205 } client_auth;
2206
2207 /*
2208 * Implementations.
2209 */
2210 br_rsa_public irsapub;
2211 #endif
2212 };
2213
2214 /**
2215 * \brief Get the hash functions and signature algorithms supported by
2216 * the server.
2217 *
2218 * This is a field of bits: for hash function of ID x, bit x is set if
2219 * the hash function is supported in RSA signatures, 8+x if it is supported
2220 * with ECDSA. This information is conveyed by the server when requesting
2221 * a client certificate.
2222 *
2223 * \param cc client context.
2224 * \return the server-supported hash functions (for signatures).
2225 */
2226 static inline uint16_t
2227 br_ssl_client_get_server_hashes(const br_ssl_client_context *cc)
2228 {
2229 return cc->hashes;
2230 }
2231
2232 /**
2233 * \brief Get the server key curve.
2234 *
2235 * This function returns the ID for the curve used by the server's public
2236 * key. This is set when the server's certificate chain is processed;
2237 * this value is 0 if the server's key is not an EC key.
2238 *
2239 * \return the server's public key curve ID, or 0.
2240 */
2241 static inline int
2242 br_ssl_client_get_server_curve(const br_ssl_client_context *cc)
2243 {
2244 return cc->server_curve;
2245 }
2246
2247 /*
2248 * Each br_ssl_client_init_xxx() function sets the list of supported
2249 * cipher suites and used implementations, as specified by the profile
2250 * name 'xxx'. Defined profile names are:
2251 *
2252 * full all supported versions and suites; constant-time implementations
2253 * TODO: add other profiles
2254 */
2255
2256 /**
2257 * \brief SSL client profile: full.
2258 *
2259 * This function initialises the provided SSL client context with
2260 * all supported algorithms and cipher suites. It also initialises
2261 * a companion X.509 validation engine with all supported algorithms,
2262 * and the provided trust anchors; the X.509 engine will be used by
2263 * the client context to validate the server's certificate.
2264 *
2265 * \param cc client context to initialise.
2266 * \param xc X.509 validation context to initialise.
2267 * \param trust_anchors trust anchors to use.
2268 * \param trust_anchors_num number of trust anchors.
2269 */
2270 void br_ssl_client_init_full(br_ssl_client_context *cc,
2271 br_x509_minimal_context *xc,
2272 const br_x509_trust_anchor *trust_anchors, size_t trust_anchors_num);
2273
2274 /**
2275 * \brief Clear the complete contents of a SSL client context.
2276 *
2277 * Everything is cleared, including the reference to the configured buffer,
2278 * implementations, cipher suites and state. This is a preparatory step
2279 * to assembling a custom profile.
2280 *
2281 * \param cc client context to clear.
2282 */
2283 void br_ssl_client_zero(br_ssl_client_context *cc);
2284
2285 /**
2286 * \brief Set an externally provided client certificate handler context.
2287 *
2288 * The handler's methods are invoked when the server requests a client
2289 * certificate.
2290 *
2291 * \param cc client context.
2292 * \param pctx certificate handler context (pointer to its vtable field).
2293 */
2294 static inline void
2295 br_ssl_client_set_client_certificate(br_ssl_client_context *cc,
2296 const br_ssl_client_certificate_class **pctx)
2297 {
2298 cc->client_auth_vtable = pctx;
2299 }
2300
2301 /**
2302 * \brief Set the RSA public-key operations implementation.
2303 *
2304 * This will be used to encrypt the pre-master secret with the server's
2305 * RSA public key (RSA-encryption cipher suites only).
2306 *
2307 * \param cc client context.
2308 * \param irsapub RSA public-key encryption implementation.
2309 */
2310 static inline void
2311 br_ssl_client_set_rsapub(br_ssl_client_context *cc, br_rsa_public irsapub)
2312 {
2313 cc->irsapub = irsapub;
2314 }
2315
2316 /**
2317 * \brief Set the minimum ClientHello length (RFC 7685 padding).
2318 *
2319 * If this value is set and the ClientHello would be shorter, then
2320 * the Pad ClientHello extension will be added with enough padding bytes
2321 * to reach the target size. Because of the extension header, the resulting
2322 * size will sometimes be slightly more than `len` bytes if the target
2323 * size cannot be exactly met.
2324 *
2325 * The target length relates to the _contents_ of the ClientHello, not
2326 * counting its 4-byte header. For instance, if `len` is set to 512,
2327 * then the padding will bring the ClientHello size to 516 bytes with its
2328 * header, and 521 bytes when counting the 5-byte record header.
2329 *
2330 * \param cc client context.
2331 * \param len minimum ClientHello length (in bytes).
2332 */
2333 static inline void
2334 br_ssl_client_set_min_clienthello_len(br_ssl_client_context *cc, uint16_t len)
2335 {
2336 cc->min_clienthello_len = len;
2337 }
2338
2339 /**
2340 * \brief Prepare or reset a client context for a new connection.
2341 *
2342 * The `server_name` parameter is used to fill the SNI extension; the
2343 * X.509 "minimal" engine will also match that name against the server
2344 * names included in the server's certificate. If the parameter is
2345 * `NULL` then no SNI extension will be sent, and the X.509 "minimal"
2346 * engine (if used for server certificate validation) will not check
2347 * presence of any specific name in the received certificate.
2348 *
2349 * Therefore, setting the `server_name` to `NULL` shall be reserved
2350 * to cases where alternate or additional methods are used to ascertain
2351 * that the right server public key is used (e.g. a "known key" model).
2352 *
2353 * If `resume_session` is non-zero and the context was previously used
2354 * then the session parameters may be reused (depending on whether the
2355 * server previously sent a non-empty session ID, and accepts the session
2356 * resumption). The session parameters for session resumption can also
2357 * be set explicitly with `br_ssl_engine_set_session_parameters()`.
2358 *
2359 * On failure, the context is marked as failed, and this function
2360 * returns 0. A possible failure condition is when no initial entropy
2361 * was injected, and none could be obtained from the OS (either OS
2362 * randomness gathering is not supported, or it failed).
2363 *
2364 * \param cc client context.
2365 * \param server_name target server name, or `NULL`.
2366 * \param resume_session non-zero to try session resumption.
2367 * \return 0 on failure, 1 on success.
2368 */
2369 int br_ssl_client_reset(br_ssl_client_context *cc,
2370 const char *server_name, int resume_session);
2371
2372 /**
2373 * \brief Forget any session in the context.
2374 *
2375 * This means that the next handshake that uses this context will
2376 * necessarily be a full handshake (this applies both to new connections
2377 * and to renegotiations).
2378 *
2379 * \param cc client context.
2380 */
2381 static inline void
2382 br_ssl_client_forget_session(br_ssl_client_context *cc)
2383 {
2384 cc->eng.session.session_id_len = 0;
2385 }
2386
2387 /**
2388 * \brief Set client certificate chain and key (single RSA case).
2389 *
2390 * This function sets a client certificate chain, that the client will
2391 * send to the server whenever a client certificate is requested. This
2392 * certificate uses an RSA public key; the corresponding private key is
2393 * invoked for authentication. Trust anchor names sent by the server are
2394 * ignored.
2395 *
2396 * The provided chain and private key are linked in the client context;
2397 * they must remain valid as long as they may be used, i.e. normally
2398 * for the duration of the connection, since they might be invoked
2399 * again upon renegotiations.
2400 *
2401 * \param cc SSL client context.
2402 * \param chain client certificate chain (SSL order: EE comes first).
2403 * \param chain_len client chain length (number of certificates).
2404 * \param sk client private key.
2405 * \param irsasign RSA signature implementation (PKCS#1 v1.5).
2406 */
2407 void br_ssl_client_set_single_rsa(br_ssl_client_context *cc,
2408 const br_x509_certificate *chain, size_t chain_len,
2409 const br_rsa_private_key *sk, br_rsa_pkcs1_sign irsasign);
2410
2411 /*
2412 * \brief Set the client certificate chain and key (single EC case).
2413 *
2414 * This function sets a client certificate chain, that the client will
2415 * send to the server whenever a client certificate is requested. This
2416 * certificate uses an EC public key; the corresponding private key is
2417 * invoked for authentication. Trust anchor names sent by the server are
2418 * ignored.
2419 *
2420 * The provided chain and private key are linked in the client context;
2421 * they must remain valid as long as they may be used, i.e. normally
2422 * for the duration of the connection, since they might be invoked
2423 * again upon renegotiations.
2424 *
2425 * The `allowed_usages` is a combination of usages, namely
2426 * `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`. The `BR_KEYTYPE_KEYX`
2427 * value allows full static ECDH, while the `BR_KEYTYPE_SIGN` value
2428 * allows ECDSA signatures. If ECDSA signatures are used, then an ECDSA
2429 * signature implementation must be provided; otherwise, the `iecdsa`
2430 * parameter may be 0.
2431 *
2432 * The `cert_issuer_key_type` value is either `BR_KEYTYPE_RSA` or
2433 * `BR_KEYTYPE_EC`; it is the type of the public key used the the CA
2434 * that issued (signed) the client certificate. That value is used with
2435 * full static ECDH: support of the certificate by the server depends
2436 * on how the certificate was signed. (Note: when using TLS 1.2, this
2437 * parameter is ignored; but its value matters for TLS 1.0 and 1.1.)
2438 *
2439 * \param cc server context.
2440 * \param chain server certificate chain to send.
2441 * \param chain_len chain length (number of certificates).
2442 * \param sk server private key (EC).
2443 * \param allowed_usages allowed private key usages.
2444 * \param cert_issuer_key_type issuing CA's key type.
2445 * \param iec EC core implementation.
2446 * \param iecdsa ECDSA signature implementation ("asn1" format).
2447 */
2448 void br_ssl_client_set_single_ec(br_ssl_client_context *cc,
2449 const br_x509_certificate *chain, size_t chain_len,
2450 const br_ec_private_key *sk, unsigned allowed_usages,
2451 unsigned cert_issuer_key_type,
2452 const br_ec_impl *iec, br_ecdsa_sign iecdsa);
2453
2454 /**
2455 * \brief Type for a "translated cipher suite", as an array of two
2456 * 16-bit integers.
2457 *
2458 * The first element is the cipher suite identifier (as used on the wire).
2459 * The second element is the concatenation of four 4-bit elements which
2460 * characterise the cipher suite contents. In most to least significant
2461 * order, these 4-bit elements are:
2462 *
2463 * - Bits 12 to 15: key exchange + server key type
2464 *
2465 * | val | symbolic constant | suite type | details |
2466 * | :-- | :----------------------- | :---------- | :----------------------------------------------- |
2467 * | 0 | `BR_SSLKEYX_RSA` | RSA | RSA key exchange, key is RSA (encryption) |
2468 * | 1 | `BR_SSLKEYX_ECDHE_RSA` | ECDHE_RSA | ECDHE key exchange, key is RSA (signature) |
2469 * | 2 | `BR_SSLKEYX_ECDHE_ECDSA` | ECDHE_ECDSA | ECDHE key exchange, key is EC (signature) |
2470 * | 3 | `BR_SSLKEYX_ECDH_RSA` | ECDH_RSA | Key is EC (key exchange), cert signed with RSA |
2471 * | 4 | `BR_SSLKEYX_ECDH_ECDSA` | ECDH_ECDSA | Key is EC (key exchange), cert signed with ECDSA |
2472 *
2473 * - Bits 8 to 11: symmetric encryption algorithm
2474 *
2475 * | val | symbolic constant | symmetric encryption | key strength (bits) |
2476 * | :-- | :--------------------- | :------------------- | :------------------ |
2477 * | 0 | `BR_SSLENC_3DES_CBC` | 3DES/CBC | 168 |
2478 * | 1 | `BR_SSLENC_AES128_CBC` | AES-128/CBC | 128 |
2479 * | 2 | `BR_SSLENC_AES256_CBC` | AES-256/CBC | 256 |
2480 * | 3 | `BR_SSLENC_AES128_GCM` | AES-128/GCM | 128 |
2481 * | 4 | `BR_SSLENC_AES256_GCM` | AES-256/GCM | 256 |
2482 * | 5 | `BR_SSLENC_CHACHA20` | ChaCha20/Poly1305 | 256 |
2483 *
2484 * - Bits 4 to 7: MAC algorithm
2485 *
2486 * | val | symbolic constant | MAC type | details |
2487 * | :-- | :----------------- | :----------- | :------------------------------------ |
2488 * | 0 | `BR_SSLMAC_AEAD` | AEAD | No dedicated MAC (encryption is AEAD) |
2489 * | 2 | `BR_SSLMAC_SHA1` | HMAC/SHA-1 | Value matches `br_sha1_ID` |
2490 * | 4 | `BR_SSLMAC_SHA256` | HMAC/SHA-256 | Value matches `br_sha256_ID` |
2491 * | 5 | `BR_SSLMAC_SHA384` | HMAC/SHA-384 | Value matches `br_sha384_ID` |
2492 *
2493 * - Bits 0 to 3: hash function for PRF when used with TLS-1.2
2494 *
2495 * | val | symbolic constant | hash function | details |
2496 * | :-- | :----------------- | :------------ | :----------------------------------- |
2497 * | 4 | `BR_SSLPRF_SHA256` | SHA-256 | Value matches `br_sha256_ID` |
2498 * | 5 | `BR_SSLPRF_SHA384` | SHA-384 | Value matches `br_sha384_ID` |
2499 *
2500 * For instance, cipher suite `TLS_RSA_WITH_AES_128_GCM_SHA256` has
2501 * standard identifier 0x009C, and is translated to 0x0304, for, in
2502 * that order: RSA key exchange (0), AES-128/GCM (3), AEAD integrity (0),
2503 * SHA-256 in the TLS PRF (4).
2504 */
2505 typedef uint16_t br_suite_translated[2];
2506
2507 #ifndef BR_DOXYGEN_IGNORE
2508 /*
2509 * Constants are already documented in the br_suite_translated type.
2510 */
2511
2512 #define BR_SSLKEYX_RSA 0
2513 #define BR_SSLKEYX_ECDHE_RSA 1
2514 #define BR_SSLKEYX_ECDHE_ECDSA 2
2515 #define BR_SSLKEYX_ECDH_RSA 3
2516 #define BR_SSLKEYX_ECDH_ECDSA 4
2517
2518 #define BR_SSLENC_3DES_CBC 0
2519 #define BR_SSLENC_AES128_CBC 1
2520 #define BR_SSLENC_AES256_CBC 2
2521 #define BR_SSLENC_AES128_GCM 3
2522 #define BR_SSLENC_AES256_GCM 4
2523 #define BR_SSLENC_CHACHA20 5
2524
2525 #define BR_SSLMAC_AEAD 0
2526 #define BR_SSLMAC_SHA1 br_sha1_ID
2527 #define BR_SSLMAC_SHA256 br_sha256_ID
2528 #define BR_SSLMAC_SHA384 br_sha384_ID
2529
2530 #define BR_SSLPRF_SHA256 br_sha256_ID
2531 #define BR_SSLPRF_SHA384 br_sha384_ID
2532
2533 #endif
2534
2535 /*
2536 * Pre-declaration for the SSL server context.
2537 */
2538 typedef struct br_ssl_server_context_ br_ssl_server_context;
2539
2540 /**
2541 * \brief Type for the server policy choices, taken after analysis of
2542 * the client message (ClientHello).
2543 */
2544 typedef struct {
2545 /**
2546 * \brief Cipher suite to use with that client.
2547 */
2548 uint16_t cipher_suite;
2549
2550 /**
2551 * \brief Hash function for signing the ServerKeyExchange.
2552 *
2553 * This is the symbolic identifier for the hash function that
2554 * will be used to sign the ServerKeyExchange message, for ECDHE
2555 * cipher suites. This is ignored for RSA and ECDH cipher suites.
2556 *
2557 * Take care that with TLS 1.0 and 1.1, that value MUST match
2558 * the protocol requirements: value must be 0 (MD5+SHA-1) for
2559 * a RSA signature, or 2 (SHA-1) for an ECDSA signature. Only
2560 * TLS 1.2 allows for other hash functions.
2561 */
2562 int hash_id;
2563
2564 /**
2565 * \brief Certificate chain to send to the client.
2566 *
2567 * This is an array of `br_x509_certificate` objects, each
2568 * normally containing a DER-encoded certificate. The server
2569 * code does not try to decode these elements.
2570 */
2571 const br_x509_certificate *chain;
2572
2573 /**
2574 * \brief Certificate chain length (number of certificates).
2575 */
2576 size_t chain_len;
2577
2578 } br_ssl_server_choices;
2579
2580 /**
2581 * \brief Class type for a policy handler (server side).
2582 *
2583 * A policy handler selects the policy parameters for a connection
2584 * (cipher suite and other algorithms, and certificate chain to send to
2585 * the client); it also performs the server-side computations involving
2586 * its permanent private key.
2587 *
2588 * The SSL server engine will invoke first `choose()`, once the
2589 * ClientHello message has been received, then either `do_keyx()`
2590 * `do_sign()`, depending on the cipher suite.
2591 */
2592 typedef struct br_ssl_server_policy_class_ br_ssl_server_policy_class;
2593 struct br_ssl_server_policy_class_ {
2594 /**
2595 * \brief Context size (in bytes).
2596 */
2597 size_t context_size;
2598
2599 /**
2600 * \brief Select algorithms and certificates for this connection.
2601 *
2602 * This callback function shall fill the provided `choices`
2603 * structure with the policy choices for this connection. This
2604 * entails selecting the cipher suite, hash function for signing
2605 * the ServerKeyExchange (applicable only to ECDHE cipher suites),
2606 * and certificate chain to send.
2607 *
2608 * The callback receives a pointer to the server context that
2609 * contains the relevant data. In particular, the functions
2610 * `br_ssl_server_get_client_suites()`,
2611 * `br_ssl_server_get_client_hashes()` and
2612 * `br_ssl_server_get_client_curves()` can be used to obtain
2613 * the cipher suites, hash functions and elliptic curves
2614 * supported by both the client and server, respectively. The
2615 * `br_ssl_engine_get_version()` and `br_ssl_engine_get_server_name()`
2616 * functions yield the protocol version and requested server name
2617 * (SNI), respectively.
2618 *
2619 * This function may modify its context structure (`pctx`) in
2620 * arbitrary ways to keep track of its own choices.
2621 *
2622 * This function shall return 1 if appropriate policy choices
2623 * could be made, or 0 if this connection cannot be pursued.
2624 *
2625 * \param pctx policy context.
2626 * \param cc SSL server context.
2627 * \param choices destination structure for the policy choices.
2628 * \return 1 on success, 0 on error.
2629 */
2630 int (*choose)(const br_ssl_server_policy_class **pctx,
2631 const br_ssl_server_context *cc,
2632 br_ssl_server_choices *choices);
2633
2634 /**
2635 * \brief Perform key exchange (server part).
2636 *
2637 * This callback is invoked to perform the server-side cryptographic
2638 * operation for a key exchange that is not ECDHE. This callback
2639 * uses the private key.
2640 *
2641 * **For RSA key exchange**, the provided `data` (of length `len`
2642 * bytes) shall be decrypted with the server's private key, and
2643 * the 48-byte premaster secret copied back to the first 48 bytes
2644 * of `data`.
2645 *
2646 * - The caller makes sure that `len` is at least 59 bytes.
2647 *
2648 * - This callback MUST check that the provided length matches
2649 * that of the key modulus; it shall report an error otherwise.
2650 *
2651 * - If the length matches that of the RSA key modulus, then
2652 * processing MUST be constant-time, even if decryption fails,
2653 * or the padding is incorrect, or the plaintext message length
2654 * is not exactly 48 bytes.
2655 *
2656 * - This callback needs not check the two first bytes of the
2657 * obtained pre-master secret (the caller will do that).
2658 *
2659 * - If an error is reported (0), then what the callback put
2660 * in the first 48 bytes of `data` is unimportant (the caller
2661 * will use random bytes instead).
2662 *
2663 * **For ECDH key exchange**, the provided `data` (of length `len`
2664 * bytes) is the elliptic curve point from the client. The
2665 * callback shall multiply it with its private key, and store
2666 * the resulting X coordinate in `data`, starting at offset 1
2667 * (thus, simply encoding the point in compressed or uncompressed
2668 * format in `data` is fine).
2669 *
2670 * - If the input array does not have the proper length for
2671 * an encoded curve point, then an error (0) shall be reported.
2672 *
2673 * - If the input array has the proper length, then processing
2674 * MUST be constant-time, even if the data is not a valid
2675 * encoded point.
2676 *
2677 * - This callback MUST check that the input point is valid.
2678 *
2679 * Returned value is 1 on success, 0 on error.
2680 *
2681 * \param pctx policy context.
2682 * \param data key exchange data from the client.
2683 * \param len key exchange data length (in bytes).
2684 * \return 1 on success, 0 on error.
2685 */
2686 uint32_t (*do_keyx)(const br_ssl_server_policy_class **pctx,
2687 unsigned char *data, size_t len);
2688
2689 /**
2690 * \brief Perform a signature (for a ServerKeyExchange message).
2691 *
2692 * This callback function is invoked for ECDHE cipher suites.
2693 * On input, the hash value to sign is in `data`, of size
2694 * `hv_len`; the involved hash function is identified by
2695 * `hash_id`. The signature shall be computed and written
2696 * back into `data`; the total size of that buffer is `len`
2697 * bytes.
2698 *
2699 * This callback shall verify that the signature length does not
2700 * exceed `len` bytes, and abstain from writing the signature if
2701 * it does not fit.
2702 *
2703 * For RSA signatures, the `hash_id` may be 0, in which case
2704 * this is the special header-less signature specified in TLS 1.0
2705 * and 1.1, with a 36-byte hash value. Otherwise, normal PKCS#1
2706 * v1.5 signatures shall be computed.
2707 *
2708 * Returned value is the signature length (in bytes), or 0 on error.
2709 *
2710 * \param pctx policy context.
2711 * \param hash_id hash function identifier.
2712 * \param hv_len hash value length (in bytes).
2713 * \param data input/output buffer (hash value, then signature).
2714 * \param len total buffer length (in bytes).
2715 * \return signature length (in bytes) on success, or 0 on error.
2716 */
2717 size_t (*do_sign)(const br_ssl_server_policy_class **pctx,
2718 int hash_id, size_t hv_len, unsigned char *data, size_t len);
2719 };
2720
2721 /**
2722 * \brief A single-chain RSA policy handler.
2723 *
2724 * This policy context uses a single certificate chain, and a RSA
2725 * private key. The context can be restricted to only signatures or
2726 * only key exchange.
2727 *
2728 * Apart from the first field (vtable pointer), its contents are
2729 * opaque and shall not be accessed directly.
2730 */
2731 typedef struct {
2732 /** \brief Pointer to vtable. */
2733 const br_ssl_server_policy_class *vtable;
2734 #ifndef BR_DOXYGEN_IGNORE
2735 const br_x509_certificate *chain;
2736 size_t chain_len;
2737 const br_rsa_private_key *sk;
2738 unsigned allowed_usages;
2739 br_rsa_private irsacore;
2740 br_rsa_pkcs1_sign irsasign;
2741 #endif
2742 } br_ssl_server_policy_rsa_context;
2743
2744 /**
2745 * \brief A single-chain EC policy handler.
2746 *
2747 * This policy context uses a single certificate chain, and an EC
2748 * private key. The context can be restricted to only signatures or
2749 * only key exchange.
2750 *
2751 * Due to how TLS is defined, this context must be made aware whether
2752 * the server certificate was itself signed with RSA or ECDSA. The code
2753 * does not try to decode the certificate to obtain that information.
2754 *
2755 * Apart from the first field (vtable pointer), its contents are
2756 * opaque and shall not be accessed directly.
2757 */
2758 typedef struct {
2759 /** \brief Pointer to vtable. */
2760 const br_ssl_server_policy_class *vtable;
2761 #ifndef BR_DOXYGEN_IGNORE
2762 const br_x509_certificate *chain;
2763 size_t chain_len;
2764 const br_ec_private_key *sk;
2765 unsigned allowed_usages;
2766 unsigned cert_issuer_key_type;
2767 const br_multihash_context *mhash;
2768 const br_ec_impl *iec;
2769 br_ecdsa_sign iecdsa;
2770 #endif
2771 } br_ssl_server_policy_ec_context;
2772
2773 /**
2774 * \brief Class type for a session parameter cache.
2775 *
2776 * Session parameters are saved in the cache with `save()`, and
2777 * retrieved with `load()`. The cache implementation can apply any
2778 * storage and eviction strategy that it sees fit. The SSL server
2779 * context that performs the request is provided, so that its
2780 * functionalities may be used by the implementation (e.g. hash
2781 * functions or random number generation).
2782 */
2783 typedef struct br_ssl_session_cache_class_ br_ssl_session_cache_class;
2784 struct br_ssl_session_cache_class_ {
2785 /**
2786 * \brief Context size (in bytes).
2787 */
2788 size_t context_size;
2789
2790 /**
2791 * \brief Record a session.
2792 *
2793 * This callback should record the provided session parameters.
2794 * The `params` structure is transient, so its contents shall
2795 * be copied into the cache. The session ID has been randomly
2796 * generated and always has length exactly 32 bytes.
2797 *
2798 * \param ctx session cache context.
2799 * \param server_ctx SSL server context.
2800 * \param params session parameters to save.
2801 */
2802 void (*save)(const br_ssl_session_cache_class **ctx,
2803 br_ssl_server_context *server_ctx,
2804 const br_ssl_session_parameters *params);
2805
2806 /**
2807 * \brief Lookup a session in the cache.
2808 *
2809 * The session ID to lookup is in `params` and always has length
2810 * exactly 32 bytes. If the session parameters are found in the
2811 * cache, then the parameters shall be copied into the `params`
2812 * structure. Returned value is 1 on successful lookup, 0
2813 * otherwise.
2814 *
2815 * \param ctx session cache context.
2816 * \param server_ctx SSL server context.
2817 * \param params destination for session parameters.
2818 * \return 1 if found, 0 otherwise.
2819 */
2820 int (*load)(const br_ssl_session_cache_class **ctx,
2821 br_ssl_server_context *server_ctx,
2822 br_ssl_session_parameters *params);
2823 };
2824
2825 /**
2826 * \brief Context for a basic cache system.
2827 *
2828 * The system stores session parameters in a buffer provided at
2829 * initialisation time. Each entry uses exactly 100 bytes, and
2830 * buffer sizes up to 4294967295 bytes are supported.
2831 *
2832 * Entries are evicted with a LRU (Least Recently Used) policy. A
2833 * search tree is maintained to keep lookups fast even with large
2834 * caches.
2835 *
2836 * Apart from the first field (vtable pointer), the structure
2837 * contents are opaque and shall not be accessed directly.
2838 */
2839 typedef struct {
2840 /** \brief Pointer to vtable. */
2841 const br_ssl_session_cache_class *vtable;
2842 #ifndef BR_DOXYGEN_IGNORE
2843 unsigned char *store;
2844 size_t store_len, store_ptr;
2845 unsigned char index_key[32];
2846 const br_hash_class *hash;
2847 int init_done;
2848 uint32_t head, tail, root;
2849 #endif
2850 } br_ssl_session_cache_lru;
2851
2852 /**
2853 * \brief Initialise a LRU session cache with the provided storage space.
2854 *
2855 * The provided storage space must remain valid as long as the cache
2856 * is used. Arbitrary lengths are supported, up to 4294967295 bytes;
2857 * each entry uses up exactly 100 bytes.
2858 *
2859 * \param cc session cache context.
2860 * \param store storage space for cached entries.
2861 * \param store_len storage space length (in bytes).
2862 */
2863 void br_ssl_session_cache_lru_init(br_ssl_session_cache_lru *cc,
2864 unsigned char *store, size_t store_len);
2865
2866 /**
2867 * \brief Context structure for a SSL server.
2868 *
2869 * The first field (called `eng`) is the SSL engine; all functions that
2870 * work on a `br_ssl_engine_context` structure shall take as parameter
2871 * a pointer to that field. The other structure fields are opaque and
2872 * must not be accessed directly.
2873 */
2874 struct br_ssl_server_context_ {
2875 /**
2876 * \brief The encapsulated engine context.
2877 */
2878 br_ssl_engine_context eng;
2879
2880 #ifndef BR_DOXYGEN_IGNORE
2881 /*
2882 * Maximum version from the client.
2883 */
2884 uint16_t client_max_version;
2885
2886 /*
2887 * Session cache.
2888 */
2889 const br_ssl_session_cache_class **cache_vtable;
2890
2891 /*
2892 * Translated cipher suites supported by the client. The list
2893 * is trimmed to include only the cipher suites that the
2894 * server also supports; they are in the same order as in the
2895 * client message.
2896 */
2897 br_suite_translated client_suites[BR_MAX_CIPHER_SUITES];
2898 unsigned char client_suites_num;
2899
2900 /*
2901 * Hash functions supported by the client, with ECDSA and RSA
2902 * (bit mask). For hash function with id 'x', set bit index is
2903 * x for RSA, x+8 for ECDSA.
2904 */
2905 uint16_t hashes;
2906
2907 /*
2908 * Curves supported by the client (bit mask, for named curves).
2909 */
2910 uint32_t curves;
2911
2912 /*
2913 * Context for chain handler.
2914 */
2915 const br_ssl_server_policy_class **policy_vtable;
2916 unsigned char sign_hash_id;
2917
2918 /*
2919 * For the core handlers, thus avoiding (in most cases) the
2920 * need for an externally provided policy context.
2921 */
2922 union {
2923 const br_ssl_server_policy_class *vtable;
2924 br_ssl_server_policy_rsa_context single_rsa;
2925 br_ssl_server_policy_ec_context single_ec;
2926 } chain_handler;
2927
2928 /*
2929 * Buffer for the ECDHE private key.
2930 */
2931 unsigned char ecdhe_key[70];
2932 size_t ecdhe_key_len;
2933
2934 /*
2935 * Trust anchor names for client authentication. "ta_names" and
2936 * "tas" cannot be both non-NULL.
2937 */
2938 const br_x500_name *ta_names;
2939 const br_x509_trust_anchor *tas;
2940 size_t num_tas;
2941 size_t cur_dn_index;
2942 const unsigned char *cur_dn;
2943 size_t cur_dn_len;
2944
2945 /*
2946 * Buffer for the hash value computed over all handshake messages
2947 * prior to CertificateVerify, and identifier for the hash function.
2948 */
2949 unsigned char hash_CV[64];
2950 size_t hash_CV_len;
2951 int hash_CV_id;
2952
2953 /*
2954 * Server-specific implementations.
2955 * (none for now)
2956 */
2957 #endif
2958 };
2959
2960 /*
2961 * Each br_ssl_server_init_xxx() function sets the list of supported
2962 * cipher suites and used implementations, as specified by the profile
2963 * name 'xxx'. Defined profile names are:
2964 *
2965 * full_rsa all supported algorithm, server key type is RSA
2966 * full_ec all supported algorithm, server key type is EC
2967 * TODO: add other profiles
2968 *
2969 * Naming scheme for "minimal" profiles: min123
2970 *
2971 * -- character 1: key exchange
2972 * r = RSA
2973 * e = ECDHE_RSA
2974 * f = ECDHE_ECDSA
2975 * u = ECDH_RSA
2976 * v = ECDH_ECDSA
2977 * -- character 2: version / PRF
2978 * 0 = TLS 1.0 / 1.1 with MD5+SHA-1
2979 * 2 = TLS 1.2 with SHA-256
2980 * 3 = TLS 1.2 with SHA-384
2981 * -- character 3: encryption
2982 * a = AES/CBC
2983 * g = AES/GCM
2984 * d = 3DES/CBC
2985 */
2986
2987 /**
2988 * \brief SSL server profile: full_rsa.
2989 *
2990 * This function initialises the provided SSL server context with
2991 * all supported algorithms and cipher suites that rely on a RSA
2992 * key pair.
2993 *
2994 * \param cc server context to initialise.
2995 * \param chain server certificate chain.
2996 * \param chain_len certificate chain length (number of certificate).
2997 * \param sk RSA private key.
2998 */
2999 void br_ssl_server_init_full_rsa(br_ssl_server_context *cc,
3000 const br_x509_certificate *chain, size_t chain_len,
3001 const br_rsa_private_key *sk);
3002
3003 /**
3004 * \brief SSL server profile: full_ec.
3005 *
3006 * This function initialises the provided SSL server context with
3007 * all supported algorithms and cipher suites that rely on an EC
3008 * key pair.
3009 *
3010 * The key type of the CA that issued the server's certificate must
3011 * be provided, since it matters for ECDH cipher suites (ECDH_RSA
3012 * suites require a RSA-powered CA). The key type is either
3013 * `BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`.
3014 *
3015 * \param cc server context to initialise.
3016 * \param chain server certificate chain.
3017 * \param chain_len chain length (number of certificates).
3018 * \param cert_issuer_key_type certificate issuer's key type.
3019 * \param sk EC private key.
3020 */
3021 void br_ssl_server_init_full_ec(br_ssl_server_context *cc,
3022 const br_x509_certificate *chain, size_t chain_len,
3023 unsigned cert_issuer_key_type, const br_ec_private_key *sk);
3024
3025 /**
3026 * \brief SSL server profile: minr2g.
3027 *
3028 * This profile uses only TLS_RSA_WITH_AES_128_GCM_SHA256. Server key is
3029 * RSA, and RSA key exchange is used (not forward secure, but uses little
3030 * CPU in the client).
3031 *
3032 * \param cc server context to initialise.
3033 * \param chain server certificate chain.
3034 * \param chain_len certificate chain length (number of certificate).
3035 * \param sk RSA private key.
3036 */
3037 void br_ssl_server_init_minr2g(br_ssl_server_context *cc,
3038 const br_x509_certificate *chain, size_t chain_len,
3039 const br_rsa_private_key *sk);
3040
3041 /**
3042 * \brief SSL server profile: mine2g.
3043 *
3044 * This profile uses only TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256. Server key
3045 * is RSA, and ECDHE key exchange is used. This suite provides forward
3046 * security, with a higher CPU expense on the client, and a somewhat
3047 * larger code footprint (compared to "minr2g").
3048 *
3049 * \param cc server context to initialise.
3050 * \param chain server certificate chain.
3051 * \param chain_len certificate chain length (number of certificate).
3052 * \param sk RSA private key.
3053 */
3054 void br_ssl_server_init_mine2g(br_ssl_server_context *cc,
3055 const br_x509_certificate *chain, size_t chain_len,
3056 const br_rsa_private_key *sk);
3057
3058 /**
3059 * \brief SSL server profile: minf2g.
3060 *
3061 * This profile uses only TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256.
3062 * Server key is EC, and ECDHE key exchange is used. This suite provides
3063 * forward security, with a higher CPU expense on the client and server
3064 * (by a factor of about 3 to 4), and a somewhat larger code footprint
3065 * (compared to "minu2g" and "minv2g").
3066 *
3067 * \param cc server context to initialise.
3068 * \param chain server certificate chain.
3069 * \param chain_len certificate chain length (number of certificate).
3070 * \param sk EC private key.
3071 */
3072 void br_ssl_server_init_minf2g(br_ssl_server_context *cc,
3073 const br_x509_certificate *chain, size_t chain_len,
3074 const br_ec_private_key *sk);
3075
3076 /**
3077 * \brief SSL server profile: minu2g.
3078 *
3079 * This profile uses only TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256.
3080 * Server key is EC, and ECDH key exchange is used; the issuing CA used
3081 * a RSA key.
3082 *
3083 * The "minu2g" and "minv2g" profiles do not provide forward secrecy,
3084 * but are the lightest on the server (for CPU usage), and are rather
3085 * inexpensive on the client as well.
3086 *
3087 * \param cc server context to initialise.
3088 * \param chain server certificate chain.
3089 * \param chain_len certificate chain length (number of certificate).
3090 * \param sk EC private key.
3091 */
3092 void br_ssl_server_init_minu2g(br_ssl_server_context *cc,
3093 const br_x509_certificate *chain, size_t chain_len,
3094 const br_ec_private_key *sk);
3095
3096 /**
3097 * \brief SSL server profile: minv2g.
3098 *
3099 * This profile uses only TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256.
3100 * Server key is EC, and ECDH key exchange is used; the issuing CA used
3101 * an EC key.
3102 *
3103 * The "minu2g" and "minv2g" profiles do not provide forward secrecy,
3104 * but are the lightest on the server (for CPU usage), and are rather
3105 * inexpensive on the client as well.
3106 *
3107 * \param cc server context to initialise.
3108 * \param chain server certificate chain.
3109 * \param chain_len certificate chain length (number of certificate).
3110 * \param sk EC private key.
3111 */
3112 void br_ssl_server_init_minv2g(br_ssl_server_context *cc,
3113 const br_x509_certificate *chain, size_t chain_len,
3114 const br_ec_private_key *sk);
3115
3116 /**
3117 * \brief SSL server profile: mine2c.
3118 *
3119 * This profile uses only TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256.
3120 * Server key is RSA, and ECDHE key exchange is used. This suite
3121 * provides forward security.
3122 *
3123 * \param cc server context to initialise.
3124 * \param chain server certificate chain.
3125 * \param chain_len certificate chain length (number of certificate).
3126 * \param sk RSA private key.
3127 */
3128 void br_ssl_server_init_mine2c(br_ssl_server_context *cc,
3129 const br_x509_certificate *chain, size_t chain_len,
3130 const br_rsa_private_key *sk);
3131
3132 /**
3133 * \brief SSL server profile: minf2c.
3134 *
3135 * This profile uses only TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256.
3136 * Server key is EC, and ECDHE key exchange is used. This suite provides
3137 * forward security.
3138 *
3139 * \param cc server context to initialise.
3140 * \param chain server certificate chain.
3141 * \param chain_len certificate chain length (number of certificate).
3142 * \param sk EC private key.
3143 */
3144 void br_ssl_server_init_minf2c(br_ssl_server_context *cc,
3145 const br_x509_certificate *chain, size_t chain_len,
3146 const br_ec_private_key *sk);
3147
3148 /**
3149 * \brief Get the supported client suites.
3150 *
3151 * This function shall be called only after the ClientHello has been
3152 * processed, typically from the policy engine. The returned array
3153 * contains the cipher suites that are supported by both the client
3154 * and the server; these suites are in client preference order, unless
3155 * the `BR_OPT_ENFORCE_SERVER_PREFERENCES` flag was set, in which case
3156 * they are in server preference order.
3157 *
3158 * The suites are _translated_, which means that each suite is given
3159 * as two 16-bit integers: the standard suite identifier, and its
3160 * translated version, broken down into its individual components,
3161 * as explained with the `br_suite_translated` type.
3162 *
3163 * The returned array is allocated in the context and will be rewritten
3164 * by each handshake.
3165 *
3166 * \param cc server context.
3167 * \param num receives the array size (number of suites).
3168 * \return the translated common cipher suites, in preference order.
3169 */
3170 static inline const br_suite_translated *
3171 br_ssl_server_get_client_suites(const br_ssl_server_context *cc, size_t *num)
3172 {
3173 *num = cc->client_suites_num;
3174 return cc->client_suites;
3175 }
3176
3177 /**
3178 * \brief Get the hash functions supported by the client.
3179 *
3180 * This is a field of bits: for hash function of ID x, bit x is set if
3181 * the hash function is supported in RSA signatures, 8+x if it is supported
3182 * with ECDSA.
3183 *
3184 * \param cc server context.
3185 * \return the client-supported hash functions (for signatures).
3186 */
3187 static inline uint16_t
3188 br_ssl_server_get_client_hashes(const br_ssl_server_context *cc)
3189 {
3190 return cc->hashes;
3191 }
3192
3193 /**
3194 * \brief Get the elliptic curves supported by the client.
3195 *
3196 * This is a bit field (bit x is set if curve of ID x is supported).
3197 *
3198 * \param cc server context.
3199 * \return the client-supported elliptic curves.
3200 */
3201 static inline uint32_t
3202 br_ssl_server_get_client_curves(const br_ssl_server_context *cc)
3203 {
3204 return cc->curves;
3205 }
3206
3207 /**
3208 * \brief Clear the complete contents of a SSL server context.
3209 *
3210 * Everything is cleared, including the reference to the configured buffer,
3211 * implementations, cipher suites and state. This is a preparatory step
3212 * to assembling a custom profile.
3213 *
3214 * \param cc server context to clear.
3215 */
3216 void br_ssl_server_zero(br_ssl_server_context *cc);
3217
3218 /**
3219 * \brief Set an externally provided policy context.
3220 *
3221 * The policy context's methods are invoked to decide the cipher suite
3222 * and certificate chain, and to perform operations involving the server's
3223 * private key.
3224 *
3225 * \param cc server context.
3226 * \param pctx policy context (pointer to its vtable field).
3227 */
3228 static inline void
3229 br_ssl_server_set_policy(br_ssl_server_context *cc,
3230 const br_ssl_server_policy_class **pctx)
3231 {
3232 cc->policy_vtable = pctx;
3233 }
3234
3235 /**
3236 * \brief Set the server certificate chain and key (single RSA case).
3237 *
3238 * This function uses a policy context included in the server context.
3239 * It configures use of a single server certificate chain with a RSA
3240 * private key. The `allowed_usages` is a combination of usages, namely
3241 * `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`; this enables or disables
3242 * the corresponding cipher suites (i.e. `TLS_RSA_*` use the RSA key for
3243 * key exchange, while `TLS_ECDHE_RSA_*` use the RSA key for signatures).
3244 *
3245 * \param cc server context.
3246 * \param chain server certificate chain to send to the client.
3247 * \param chain_len chain length (number of certificates).
3248 * \param sk server private key (RSA).
3249 * \param allowed_usages allowed private key usages.
3250 * \param irsacore RSA core implementation.
3251 * \param irsasign RSA signature implementation (PKCS#1 v1.5).
3252 */
3253 void br_ssl_server_set_single_rsa(br_ssl_server_context *cc,
3254 const br_x509_certificate *chain, size_t chain_len,
3255 const br_rsa_private_key *sk, unsigned allowed_usages,
3256 br_rsa_private irsacore, br_rsa_pkcs1_sign irsasign);
3257
3258 /**
3259 * \brief Set the server certificate chain and key (single EC case).
3260 *
3261 * This function uses a policy context included in the server context.
3262 * It configures use of a single server certificate chain with an EC
3263 * private key. The `allowed_usages` is a combination of usages, namely
3264 * `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`; this enables or disables
3265 * the corresponding cipher suites (i.e. `TLS_ECDH_*` use the EC key for
3266 * key exchange, while `TLS_ECDHE_ECDSA_*` use the EC key for signatures).
3267 *
3268 * In order to support `TLS_ECDH_*` cipher suites (non-ephemeral ECDH),
3269 * the algorithm type of the key used by the issuing CA to sign the
3270 * server's certificate must be provided, as `cert_issuer_key_type`
3271 * parameter (this value is either `BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`).
3272 *
3273 * \param cc server context.
3274 * \param chain server certificate chain to send.
3275 * \param chain_len chain length (number of certificates).
3276 * \param sk server private key (EC).
3277 * \param allowed_usages allowed private key usages.
3278 * \param cert_issuer_key_type issuing CA's key type.
3279 * \param iec EC core implementation.
3280 * \param iecdsa ECDSA signature implementation ("asn1" format).
3281 */
3282 void br_ssl_server_set_single_ec(br_ssl_server_context *cc,
3283 const br_x509_certificate *chain, size_t chain_len,
3284 const br_ec_private_key *sk, unsigned allowed_usages,
3285 unsigned cert_issuer_key_type,
3286 const br_ec_impl *iec, br_ecdsa_sign iecdsa);
3287
3288 /**
3289 * \brief Activate client certificate authentication.
3290 *
3291 * The trust anchor encoded X.500 names (DN) to send to the client are
3292 * provided. A client certificate will be requested and validated through
3293 * the X.509 validator configured in the SSL engine. If `num` is 0, then
3294 * client certificate authentication is disabled.
3295 *
3296 * If the client does not send a certificate, or on validation failure,
3297 * the handshake aborts. Unauthenticated clients can be tolerated by
3298 * setting the `BR_OPT_TOLERATE_NO_CLIENT_AUTH` flag.
3299 *
3300 * The provided array is linked in, not copied, so that pointer must
3301 * remain valid as long as anchor names may be used.
3302 *
3303 * \param cc server context.
3304 * \param ta_names encoded trust anchor names.
3305 * \param num number of encoded trust anchor names.
3306 */
3307 static inline void
3308 br_ssl_server_set_trust_anchor_names(br_ssl_server_context *cc,
3309 const br_x500_name *ta_names, size_t num)
3310 {
3311 cc->ta_names = ta_names;
3312 cc->tas = NULL;
3313 cc->num_tas = num;
3314 }
3315
3316 /**
3317 * \brief Activate client certificate authentication.
3318 *
3319 * This is a variant for `br_ssl_server_set_trust_anchor_names()`: the
3320 * trust anchor names are provided not as an array of stand-alone names
3321 * (`br_x500_name` structures), but as an array of trust anchors
3322 * (`br_x509_trust_anchor` structures). The server engine itself will
3323 * only use the `dn` field of each trust anchor. This is meant to allow
3324 * defining a single array of trust anchors, to be used here and in the
3325 * X.509 validation engine itself.
3326 *
3327 * The provided array is linked in, not copied, so that pointer must
3328 * remain valid as long as anchor names may be used.
3329 *
3330 * \param cc server context.
3331 * \param tas trust anchors (only names are used).
3332 * \param num number of trust anchors.
3333 */
3334 static inline void
3335 br_ssl_server_set_trust_anchor_names_alt(br_ssl_server_context *cc,
3336 const br_x509_trust_anchor *tas, size_t num)
3337 {
3338 cc->ta_names = NULL;
3339 cc->tas = tas;
3340 cc->num_tas = num;
3341 }
3342
3343 /**
3344 * \brief Configure the cache for session parameters.
3345 *
3346 * The cache context is provided as a pointer to its first field (vtable
3347 * pointer).
3348 *
3349 * \param cc server context.
3350 * \param vtable session cache context.
3351 */
3352 static inline void
3353 br_ssl_server_set_cache(br_ssl_server_context *cc,
3354 const br_ssl_session_cache_class **vtable)
3355 {
3356 cc->cache_vtable = vtable;
3357 }
3358
3359 /**
3360 * \brief Prepare or reset a server context for handling an incoming client.
3361 *
3362 * \param cc server context.
3363 * \return 1 on success, 0 on error.
3364 */
3365 int br_ssl_server_reset(br_ssl_server_context *cc);
3366
3367 /* ===================================================================== */
3368
3369 /*
3370 * Context for the simplified I/O context. The transport medium is accessed
3371 * through the low_read() and low_write() callback functions, each with
3372 * its own opaque context pointer.
3373 *
3374 * low_read() read some bytes, at most 'len' bytes, into data[]. The
3375 * returned value is the number of read bytes, or -1 on error.
3376 * The 'len' parameter is guaranteed never to exceed 20000,
3377 * so the length always fits in an 'int' on all platforms.
3378 *
3379 * low_write() write up to 'len' bytes, to be read from data[]. The
3380 * returned value is the number of written bytes, or -1 on
3381 * error. The 'len' parameter is guaranteed never to exceed
3382 * 20000, so the length always fits in an 'int' on all
3383 * parameters.
3384 *
3385 * A socket closure (if the transport medium is a socket) should be reported
3386 * as an error (-1). The callbacks shall endeavour to block until at least
3387 * one byte can be read or written; a callback returning 0 at times is
3388 * acceptable, but this normally leads to the callback being immediately
3389 * called again, so the callback should at least always try to block for
3390 * some time if no I/O can take place.
3391 *
3392 * The SSL engine naturally applies some buffering, so the callbacks need
3393 * not apply buffers of their own.
3394 */
3395 /**
3396 * \brief Context structure for the simplified SSL I/O wrapper.
3397 *
3398 * This structure is initialised with `br_sslio_init()`. Its contents
3399 * are opaque and shall not be accessed directly.
3400 */
3401 typedef struct {
3402 #ifndef BR_DOXYGEN_IGNORE
3403 br_ssl_engine_context *engine;
3404 int (*low_read)(void *read_context,
3405 unsigned char *data, size_t len);
3406 void *read_context;
3407 int (*low_write)(void *write_context,
3408 const unsigned char *data, size_t len);
3409 void *write_context;
3410 #endif
3411 } br_sslio_context;
3412
3413 /**
3414 * \brief Initialise a simplified I/O wrapper context.
3415 *
3416 * The simplified I/O wrapper offers a simpler read/write API for a SSL
3417 * engine (client or server), using the provided callback functions for
3418 * reading data from, or writing data to, the transport medium.
3419 *
3420 * The callback functions have the following semantics:
3421 *
3422 * - Each callback receives an opaque context value (of type `void *`)
3423 * that the callback may use arbitrarily (or possibly ignore).
3424 *
3425 * - `low_read()` reads at least one byte, at most `len` bytes, from
3426 * the transport medium. Read bytes shall be written in `data`.
3427 *
3428 * - `low_write()` writes at least one byte, at most `len` bytes, unto
3429 * the transport medium. The bytes to write are read from `data`.
3430 *
3431 * - The `len` parameter is never zero, and is always lower than 20000.
3432 *
3433 * - The number of processed bytes (read or written) is returned. Since
3434 * that number is less than 20000, it always fits on an `int`.
3435 *
3436 * - On error, the callbacks return -1. Reaching end-of-stream is an
3437 * error. Errors are permanent: the SSL connection is terminated.
3438 *
3439 * - Callbacks SHOULD NOT return 0. This is tolerated, as long as
3440 * callbacks endeavour to block for some non-negligible amount of
3441 * time until at least one byte can be sent or received (if a
3442 * callback returns 0, then the wrapper invokes it again
3443 * immediately).
3444 *
3445 * - Callbacks MAY return as soon as at least one byte is processed;
3446 * they MAY also insist on reading or writing _all_ requested bytes.
3447 * Since SSL is a self-terminated protocol (each record has a length
3448 * header), this does not change semantics.
3449 *
3450 * - Callbacks need not apply any buffering (for performance) since SSL
3451 * itself uses buffers.
3452 *
3453 * \param ctx wrapper context to initialise.
3454 * \param engine SSL engine to wrap.
3455 * \param low_read callback for reading data from the transport.
3456 * \param read_context context pointer for `low_read()`.
3457 * \param low_write callback for writing data on the transport.
3458 * \param write_context context pointer for `low_write()`.
3459 */
3460 void br_sslio_init(br_sslio_context *ctx,
3461 br_ssl_engine_context *engine,
3462 int (*low_read)(void *read_context,
3463 unsigned char *data, size_t len),
3464 void *read_context,
3465 int (*low_write)(void *write_context,
3466 const unsigned char *data, size_t len),
3467 void *write_context);
3468
3469 /**
3470 * \brief Read some application data from a SSL connection.
3471 *
3472 * If `len` is zero, then this function returns 0 immediately. In
3473 * all other cases, it never returns 0.
3474 *
3475 * This call returns only when at least one byte has been obtained.
3476 * Returned value is the number of bytes read, or -1 on error. The
3477 * number of bytes always fits on an 'int' (data from a single SSL/TLS
3478 * record is returned).
3479 *
3480 * On error or SSL closure, this function returns -1. The caller should
3481 * inspect the error status on the SSL engine to distinguish between
3482 * normal closure and error.
3483 *
3484 * \param cc SSL wrapper context.
3485 * \param dst destination buffer for application data.
3486 * \param len maximum number of bytes to obtain.
3487 * \return number of bytes obtained, or -1 on error.
3488 */
3489 int br_sslio_read(br_sslio_context *cc, void *dst, size_t len);
3490
3491 /**
3492 * \brief Read application data from a SSL connection.
3493 *
3494 * This calls returns only when _all_ requested `len` bytes are read,
3495 * or an error is reached. Returned value is 0 on success, -1 on error.
3496 * A normal (verified) SSL closure before that many bytes are obtained
3497 * is reported as an error by this function.
3498 *
3499 * \param cc SSL wrapper context.
3500 * \param dst destination buffer for application data.
3501 * \param len number of bytes to obtain.
3502 * \return 0 on success, or -1 on error.
3503 */
3504 int br_sslio_read_all(br_sslio_context *cc, void *dst, size_t len);
3505
3506 /**
3507 * \brief Write some application data unto a SSL connection.
3508 *
3509 * If `len` is zero, then this function returns 0 immediately. In
3510 * all other cases, it never returns 0.
3511 *
3512 * This call returns only when at least one byte has been written.
3513 * Returned value is the number of bytes written, or -1 on error. The
3514 * number of bytes always fits on an 'int' (less than 20000).
3515 *
3516 * On error or SSL closure, this function returns -1. The caller should
3517 * inspect the error status on the SSL engine to distinguish between
3518 * normal closure and error.
3519 *
3520 * **Important:** SSL is buffered; a "written" byte is a byte that was
3521 * injected into the wrapped SSL engine, but this does not necessarily mean
3522 * that it has been scheduled for sending. Use `br_sslio_flush()` to
3523 * ensure that all pending data has been sent to the transport medium.
3524 *
3525 * \param cc SSL wrapper context.
3526 * \param src source buffer for application data.
3527 * \param len maximum number of bytes to write.
3528 * \return number of bytes written, or -1 on error.
3529 */
3530 int br_sslio_write(br_sslio_context *cc, const void *src, size_t len);
3531
3532 /**
3533 * \brief Write application data unto a SSL connection.
3534 *
3535 * This calls returns only when _all_ requested `len` bytes have been
3536 * written, or an error is reached. Returned value is 0 on success, -1
3537 * on error. A normal (verified) SSL closure before that many bytes are
3538 * written is reported as an error by this function.
3539 *
3540 * **Important:** SSL is buffered; a "written" byte is a byte that was
3541 * injected into the wrapped SSL engine, but this does not necessarily mean
3542 * that it has been scheduled for sending. Use `br_sslio_flush()` to
3543 * ensure that all pending data has been sent to the transport medium.
3544 *
3545 * \param cc SSL wrapper context.
3546 * \param src source buffer for application data.
3547 * \param len number of bytes to write.
3548 * \return 0 on success, or -1 on error.
3549 */
3550 int br_sslio_write_all(br_sslio_context *cc, const void *src, size_t len);
3551
3552 /**
3553 * \brief Flush pending data.
3554 *
3555 * This call makes sure that any buffered application data in the
3556 * provided context (including the wrapped SSL engine) has been sent
3557 * to the transport medium (i.e. accepted by the `low_write()` callback
3558 * method). If there is no such pending data, then this function does
3559 * nothing (and returns a success, i.e. 0).
3560 *
3561 * If the underlying transport medium has its own buffers, then it is
3562 * up to the caller to ensure the corresponding flushing.
3563 *
3564 * Returned value is 0 on success, -1 on error.
3565 *
3566 * \param cc SSL wrapper context.
3567 * \return 0 on success, or -1 on error.
3568 */
3569 int br_sslio_flush(br_sslio_context *cc);
3570
3571 /**
3572 * \brief Close the SSL connection.
3573 *
3574 * This call runs the SSL closure protocol (sending a `close_notify`,
3575 * receiving the response `close_notify`). When it returns, the SSL
3576 * connection is finished. It is still up to the caller to manage the
3577 * possible transport-level termination, if applicable (alternatively,
3578 * the underlying transport stream may be reused for non-SSL messages).
3579 *
3580 * Returned value is 0 on success, -1 on error. A failure by the peer
3581 * to process the complete closure protocol (i.e. sending back the
3582 * `close_notify`) is an error.
3583 *
3584 * \param cc SSL wrapper context.
3585 * \return 0 on success, or -1 on error.
3586 */
3587 int br_sslio_close(br_sslio_context *cc);
3588
3589 /* ===================================================================== */
3590
3591 /*
3592 * Symbolic constants for cipher suites.
3593 */
3594
3595 /* From RFC 5246 */
3596 #define BR_TLS_NULL_WITH_NULL_NULL 0x0000
3597 #define BR_TLS_RSA_WITH_NULL_MD5 0x0001
3598 #define BR_TLS_RSA_WITH_NULL_SHA 0x0002
3599 #define BR_TLS_RSA_WITH_NULL_SHA256 0x003B
3600 #define BR_TLS_RSA_WITH_RC4_128_MD5 0x0004
3601 #define BR_TLS_RSA_WITH_RC4_128_SHA 0x0005
3602 #define BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA 0x000A
3603 #define BR_TLS_RSA_WITH_AES_128_CBC_SHA 0x002F
3604 #define BR_TLS_RSA_WITH_AES_256_CBC_SHA 0x0035
3605 #define BR_TLS_RSA_WITH_AES_128_CBC_SHA256 0x003C
3606 #define BR_TLS_RSA_WITH_AES_256_CBC_SHA256 0x003D
3607 #define BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 0x000D
3608 #define BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 0x0010
3609 #define BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 0x0013
3610 #define BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 0x0016
3611 #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA 0x0030
3612 #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA 0x0031
3613 #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA 0x0032
3614 #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA 0x0033
3615 #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA 0x0036
3616 #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA 0x0037
3617 #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA 0x0038
3618 #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x0039
3619 #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256 0x003E
3620 #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256 0x003F
3621 #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 0x0040
3622 #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 0x0067
3623 #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256 0x0068
3624 #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256 0x0069
3625 #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 0x006A
3626 #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 0x006B
3627 #define BR_TLS_DH_anon_WITH_RC4_128_MD5 0x0018
3628 #define BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 0x001B
3629 #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA 0x0034
3630 #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA 0x003A
3631 #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256 0x006C
3632 #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256 0x006D
3633
3634 /* From RFC 4492 */
3635 #define BR_TLS_ECDH_ECDSA_WITH_NULL_SHA 0xC001
3636 #define BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0xC002
3637 #define BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC003
3638 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0xC004
3639 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0xC005
3640 #define BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA 0xC006
3641 #define BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0xC007
3642 #define BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC008
3643 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0xC009
3644 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0xC00A
3645 #define BR_TLS_ECDH_RSA_WITH_NULL_SHA 0xC00B
3646 #define BR_TLS_ECDH_RSA_WITH_RC4_128_SHA 0xC00C
3647 #define BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0xC00D
3648 #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0xC00E
3649 #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0xC00F
3650 #define BR_TLS_ECDHE_RSA_WITH_NULL_SHA 0xC010
3651 #define BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA 0xC011
3652 #define BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0xC012
3653 #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0xC013
3654 #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC014
3655 #define BR_TLS_ECDH_anon_WITH_NULL_SHA 0xC015
3656 #define BR_TLS_ECDH_anon_WITH_RC4_128_SHA 0xC016
3657 #define BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 0xC017
3658 #define BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA 0xC018
3659 #define BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA 0xC019
3660
3661 /* From RFC 5288 */
3662 #define BR_TLS_RSA_WITH_AES_128_GCM_SHA256 0x009C
3663 #define BR_TLS_RSA_WITH_AES_256_GCM_SHA384 0x009D
3664 #define BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 0x009E
3665 #define BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 0x009F
3666 #define BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256 0x00A0
3667 #define BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384 0x00A1
3668 #define BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 0x00A2
3669 #define BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 0x00A3
3670 #define BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256 0x00A4
3671 #define BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384 0x00A5
3672 #define BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256 0x00A6
3673 #define BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384 0x00A7
3674
3675 /* From RFC 5289 */
3676 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023
3677 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024
3678 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC025
3679 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0xC026
3680 #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0xC027
3681 #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC028
3682 #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0xC029
3683 #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0xC02A
3684 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B
3685 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C
3686 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 0xC02D
3687 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 0xC02E
3688 #define BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC02F
3689 #define BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xC030
3690 #define BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 0xC031
3691 #define BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 0xC032
3692
3693 /* From RFC 7905 */
3694 #define BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8
3695 #define BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9
3696 #define BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCAA
3697 #define BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAB
3698 #define BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAC
3699 #define BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAD
3700 #define BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAE
3701
3702 /* From RFC 7507 */
3703 #define BR_TLS_FALLBACK_SCSV 0x5600
3704
3705 /*
3706 * Symbolic constants for alerts.
3707 */
3708 #define BR_ALERT_CLOSE_NOTIFY 0
3709 #define BR_ALERT_UNEXPECTED_MESSAGE 10
3710 #define BR_ALERT_BAD_RECORD_MAC 20
3711 #define BR_ALERT_RECORD_OVERFLOW 22
3712 #define BR_ALERT_DECOMPRESSION_FAILURE 30
3713 #define BR_ALERT_HANDSHAKE_FAILURE 40
3714 #define BR_ALERT_BAD_CERTIFICATE 42
3715 #define BR_ALERT_UNSUPPORTED_CERTIFICATE 43
371