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