2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
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:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
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
25 #ifndef BR_BEARSSL_SSL_H__
26 #define BR_BEARSSL_SSL_H__
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"
44 /* Optimal input buffer size. */
45 #define BR_SSL_BUFSIZE_INPUT (16384 + 325)
47 /* Optimal output buffer size. */
48 #define BR_SSL_BUFSIZE_OUTPUT (16384 + 85)
50 /* Optimal buffer size for monodirectional engine
51 (shared input/output buffer). */
52 #define BR_SSL_BUFSIZE_MONO BR_SSL_BUFSIZE_INPUT
54 /* Optimal buffer size for bidirectional engine
55 (single buffer split into two separate input/output buffers). */
56 #define BR_SSL_BUFSIZE_BIDI (BR_SSL_BUFSIZE_INPUT + BR_SSL_BUFSIZE_OUTPUT)
59 * Constants for known SSL/TLS protocol versions (SSL 3.0, TLS 1.0, TLS 1.1
60 * and TLS 1.2). Note that though there is a constant for SSL 3.0, that
61 * protocol version is not actually supported.
63 #define BR_SSL30 0x0300
64 #define BR_TLS10 0x0301
65 #define BR_TLS11 0x0302
66 #define BR_TLS12 0x0303
69 * Error constants. They are used to report the reason why a context has
70 * been marked as failed.
72 * Implementation note: SSL-level error codes should be in the 1..31
73 * range. The 32..63 range is for certificate decoding and validation
74 * errors. Received fatal alerts imply an error code in the 256..511 range.
77 /* No error so far (0). */
80 /* Caller-provided parameter is incorrect. */
81 #define BR_ERR_BAD_PARAM 1
83 /* Operation requested by the caller cannot be applied with the current
84 context state (e.g. reading data while outgoing data is waiting to
86 #define BR_ERR_BAD_STATE 2
88 /* Incoming protocol or record version is unsupported. */
89 #define BR_ERR_UNSUPPORTED_VERSION 3
91 /* Incoming record version does not match the expected version. */
92 #define BR_ERR_BAD_VERSION 4
94 /* Incoming record length is invalid. */
95 #define BR_ERR_BAD_LENGTH 5
97 /* Incoming record is too large to be processed, or buffer is too small
98 for the handshake message to send. */
99 #define BR_ERR_TOO_LARGE 6
101 /* Decryption found an invalid padding, or the record MAC is not correct. */
102 #define BR_ERR_BAD_MAC 7
104 /* No initial entropy was provided, and none can be obtained from the OS. */
105 #define BR_ERR_NO_RANDOM 8
107 /* Incoming record type is unknown. */
108 #define BR_ERR_UNKNOWN_TYPE 9
110 /* Incoming record or message has wrong type with regards to the
111 current engine state. */
112 #define BR_ERR_UNEXPECTED 10
114 /* ChangeCipherSpec message from the peer has invalid contents. */
115 #define BR_ERR_BAD_CCS 12
117 /* Alert message from the peer has invalid contents (odd length). */
118 #define BR_ERR_BAD_ALERT 13
120 /* Incoming handshake message decoding failed. */
121 #define BR_ERR_BAD_HANDSHAKE 14
123 /* ServerHello contains a session ID which is larger than 32 bytes. */
124 #define BR_ERR_OVERSIZED_ID 15
126 /* Server wants to use a cipher suite that we did not claim to support.
127 This is also reported if we tried to advertise a cipher suite that
128 we do not support. */
129 #define BR_ERR_BAD_CIPHER_SUITE 16
131 /* Server wants to use a compression that we did not claim to support. */
132 #define BR_ERR_BAD_COMPRESSION 17
134 /* Server's max fragment length does not match client's. */
135 #define BR_ERR_BAD_FRAGLEN 18
137 /* Secure renegotiation failed. */
138 #define BR_ERR_BAD_SECRENEG 19
140 /* Server sent an extension type that we did not announce, or used the
141 same extension type several times in a single ServerHello. */
142 #define BR_ERR_EXTRA_EXTENSION 20
144 /* Invalid Server Name Indication contents (when used by the server,
145 this extension shall be empty). */
146 #define BR_ERR_BAD_SNI 21
148 /* Invalid ServerHelloDone from the server (length is not 0). */
149 #define BR_ERR_BAD_HELLO_DONE 22
151 /* Internal limit exceeded (e.g. server's public key is too large). */
152 #define BR_ERR_LIMIT_EXCEEDED 23
154 /* Finished message from peer does not match the expected value. */
155 #define BR_ERR_BAD_FINISHED 24
157 /* Session resumption attempt with distinct version or cipher suite. */
158 #define BR_ERR_RESUME_MISMATCH 25
160 /* Unsupported or invalid algorithm (ECDHE curve, signature algorithm,
162 #define BR_ERR_INVALID_ALGORITHM 26
164 /* Invalid signature on ServerKeyExchange message. */
165 #define BR_ERR_BAD_SIGNATURE 27
167 /* I/O error or premature close on underlying transport stream. This
168 error code is set only by the simplified I/O API ("br_sslio_*"). */
171 /* When a fatal alert is received from the peer, the alert value is added
173 #define BR_ERR_RECV_FATAL_ALERT 256
175 /* When a fatal alert is sent to the peer, the alert value is added
177 #define BR_ERR_SEND_FATAL_ALERT 512
179 /* ===================================================================== */
182 * The decryption engine for incoming records is an object that implements
183 * the following functions:
185 * check_length test whether the provided record length is valid
186 * decrypt decrypt and verify the provided record
188 * The decrypt() function receives as parameters a pointer to its context
189 * structure, the record type, the record version, a pointer to the
190 * start of the record payload, and a pointer to a word containing the
191 * payload length. The decrypt() function may assume that the length is
192 * proper (check_length() was called and returned 1). On success, a
193 * pointer to the first plaintext byte is returned, and *len is adjusted
194 * to contain the plaintext length; on error, NULL is returned.
196 * The decryption engine is responsible for keeping track of the record
199 typedef struct br_sslrec_in_class_ br_sslrec_in_class
;
200 struct br_sslrec_in_class_
{
202 int (*check_length
)(const br_sslrec_in_class
*const *ctx
,
204 unsigned char *(*decrypt
)(const br_sslrec_in_class
**ctx
,
205 int record_type
, unsigned version
,
206 void *payload
, size_t *len
);
210 * The encryption engine for outgoing records is an object that implements
211 * the following functions:
213 * max_plaintext get start and end offsets for payload
214 * encrypt encrypt and apply MAC on current record
216 * The max_plaintext() function receives as inputs the start and end
217 * of the buffer where the payload will be stored; this function assumes
218 * that there will be room for a record header (5 bytes) BEFORE the
219 * offset specified by *start. The max_plaintext() function then adjusts
220 * the two offsets to designate the area for the plaintext.
222 * The encrypt() function assumes that the provided plaintext data is
223 * in a buffer with enough room before and after the data chunk to
224 * receive the needed headers (i.e. the plaintext is at offsets which
225 * were computed by an earlier call to max_plaintext()). It returns
226 * a pointer to the start of the encrypted record, and writes the
227 * encrypted record length in '*len' (that length includes the record
230 * The encryption engine MUST fill the record header. If the engine
231 * performs a "split" into several records, then the successive records
232 * MUST be consecutive in RAM; the returned length is thus the sum of
233 * the individual record lengths.
235 * The encryption engine is responsible for keeping track of the record
238 typedef struct br_sslrec_out_class_ br_sslrec_out_class
;
239 struct br_sslrec_out_class_
{
241 void (*max_plaintext
)(const br_sslrec_out_class
*const *ctx
,
242 size_t *start
, size_t *end
);
243 unsigned char *(*encrypt
)(const br_sslrec_out_class
**ctx
,
244 int record_type
, unsigned version
,
245 void *plaintext
, size_t *len
);
249 * An outgoing no-encryption engine is defined, to process outgoing
250 * records before completion of the initial handshake.
253 const br_sslrec_out_class
*vtable
;
254 } br_sslrec_out_clear_context
;
255 extern const br_sslrec_out_class br_sslrec_out_clear_vtable
;
257 /* ===================================================================== */
260 * An engine for processing incoming records with a block cipher in
261 * CBC mode has an extra initialization function, that takes as inputs:
262 * -- a block cipher (CBC decryption) and its key;
263 * -- a hash function for HMAC, with the MAC key and output length;
264 * -- an optional initial IV.
265 * If the IV is not provided (the 'iv' parameter is NULL), then the
266 * engine will use an explicit per-record IV (as is mandated in TLS 1.1+).
268 * The initialization function is responsible for setting the 'vtable'
269 * field of the context.
271 typedef struct br_sslrec_in_cbc_class_ br_sslrec_in_cbc_class
;
272 struct br_sslrec_in_cbc_class_
{
273 br_sslrec_in_class inner
;
274 void (*init
)(const br_sslrec_in_cbc_class
**ctx
,
275 const br_block_cbcdec_class
*bc_impl
,
276 const void *bc_key
, size_t bc_key_len
,
277 const br_hash_class
*dig_impl
,
278 const void *mac_key
, size_t mac_key_len
, size_t mac_out_len
,
283 * An engine for processing outgoing records with a block cipher in
284 * CBC mode has an extra initialization function, that takes as inputs:
285 * -- a block cipher (CBC encryption) and its key;
286 * -- a hash function for HMAC, with the MAC key and output length;
287 * -- an optional initial IV.
288 * If the IV is not provided (the 'iv' parameter is NULL), then the
289 * engine will use an explicit per-record IV (as is mandated in TLS 1.1+).
291 * The initialization function is responsible for setting the 'vtable'
292 * field of the context.
294 typedef struct br_sslrec_out_cbc_class_ br_sslrec_out_cbc_class
;
295 struct br_sslrec_out_cbc_class_
{
296 br_sslrec_out_class inner
;
297 void (*init
)(const br_sslrec_out_cbc_class
**ctx
,
298 const br_block_cbcenc_class
*bc_impl
,
299 const void *bc_key
, size_t bc_key_len
,
300 const br_hash_class
*dig_impl
,
301 const void *mac_key
, size_t mac_key_len
, size_t mac_out_len
,
306 * Context structure for decrypting incoming records with CBC + HMAC.
309 const br_sslrec_in_cbc_class
*vtable
;
312 const br_block_cbcdec_class
*vtable
;
313 br_aes_gen_cbcdec_keys aes
;
314 br_des_gen_cbcdec_keys des
;
316 br_hmac_key_context mac
;
318 unsigned char iv
[16];
320 } br_sslrec_in_cbc_context
;
321 extern const br_sslrec_in_cbc_class br_sslrec_in_cbc_vtable
;
324 * Context structure for encrypting outgoing records with CBC + HMAC.
327 const br_sslrec_out_cbc_class
*vtable
;
330 const br_block_cbcenc_class
*vtable
;
331 br_aes_gen_cbcenc_keys aes
;
332 br_des_gen_cbcenc_keys des
;
334 br_hmac_key_context mac
;
336 unsigned char iv
[16];
338 } br_sslrec_out_cbc_context
;
339 extern const br_sslrec_out_cbc_class br_sslrec_out_cbc_vtable
;
341 /* ===================================================================== */
344 * An engine for processing incoming records with a block cipher in
345 * GCM mode has an extra initialization function, that takes as inputs:
346 * -- a block cipher (CTR) and its key;
347 * -- a GHASH implementation;
348 * -- an initial IV (4 bytes).
350 * The initialization function is responsible for setting the 'vtable'
351 * field of the context.
353 typedef struct br_sslrec_in_gcm_class_ br_sslrec_in_gcm_class
;
354 struct br_sslrec_in_gcm_class_
{
355 br_sslrec_in_class inner
;
356 void (*init
)(const br_sslrec_in_gcm_class
**ctx
,
357 const br_block_ctr_class
*bc_impl
,
358 const void *key
, size_t key_len
,
364 * An engine for processing outgoing records with a block cipher in
365 * GCM mode has an extra initialization function, that takes as inputs:
366 * -- a block cipher (CTR) and its key;
367 * -- a GHASH implementation;
368 * -- an initial IV (4 bytes).
370 * The initialization function is responsible for setting the 'vtable'
371 * field of the context.
373 typedef struct br_sslrec_out_gcm_class_ br_sslrec_out_gcm_class
;
374 struct br_sslrec_out_gcm_class_
{
375 br_sslrec_out_class inner
;
376 void (*init
)(const br_sslrec_out_gcm_class
**ctx
,
377 const br_block_ctr_class
*bc_impl
,
378 const void *key
, size_t key_len
,
384 * We use the same context structure for incoming and outgoing records
385 * with GCM, because it allows internal code sharing.
390 const br_sslrec_in_gcm_class
*in
;
391 const br_sslrec_out_gcm_class
*out
;
395 const br_block_ctr_class
*vtable
;
396 br_aes_gen_ctr_keys aes
;
401 } br_sslrec_gcm_context
;
403 extern const br_sslrec_in_gcm_class br_sslrec_in_gcm_vtable
;
404 extern const br_sslrec_out_gcm_class br_sslrec_out_gcm_vtable
;
406 /* ===================================================================== */
409 * Type for session parameters, to be saved for session resumption.
412 unsigned char session_id
[32];
413 unsigned char session_id_len
;
415 uint16_t cipher_suite
;
416 unsigned char master_secret
[48];
417 } br_ssl_session_parameters
;
420 * Maximum numnber of cipher suites supported by a client or server.
422 #define BR_MAX_CIPHER_SUITES 40
425 * Context structure for SSL engine. This is common to the client and
426 * server; the engine manages records, including alerts, closures, and
427 * transitions to new encryption/MAC algorithms. Processing of handshake
428 * records is delegated to externally provided code. This structure
429 * should not be used directly, but is meant to be included as first
430 * field of the context structures for SSL clients and servers.
435 * The error code. When non-zero, then the state is "failed" and
436 * no I/O may occur until reset.
441 * Configured I/O buffers. They are either disjoint, or identical.
443 unsigned char *ibuf
, *obuf
;
444 size_t ibuf_len
, obuf_len
;
447 * Maximum fragment length applies to outgoing records; incoming
448 * records can be processed as long as they fit in the input
449 * buffer. It is guaranteed that incoming records at least as big
450 * as max_frag_len can be processed.
452 uint16_t max_frag_len
;
453 unsigned char log_max_frag_len
;
454 unsigned char peer_log_max_frag_len
;
457 * Buffering management registers.
459 size_t ixa
, ixb
, ixc
;
460 size_t oxa
, oxb
, oxc
;
461 unsigned char iomode
;
462 unsigned char incrypt
;
465 * Shutdown flag: when set to non-zero, incoming record bytes
466 * will not be accepted anymore. This is used after a close_notify
467 * has been received: afterwards, the engine no longer claims that
468 * it could receive bytes from the transport medium.
470 unsigned char shutdown_recv
;
473 * 'record_type_in' is set to the incoming record type when the
474 * record header has been received.
475 * 'record_type_out' is used to make the next outgoing record
476 * header when it is ready to go.
478 unsigned char record_type_in
, record_type_out
;
481 * When a record is received, its version is extracted:
482 * -- if 'version_in' is 0, then it is set to the received version;
483 * -- otherwise, if the received version is not identical to
484 * the 'version_in' contents, then a failure is reported.
486 * This implements the SSL requirement that all records shall
487 * use the negotiated protocol version, once decided (in the
488 * ServerHello). It is up to the handshake handler to adjust this
489 * field when necessary.
494 * 'version_out' is used when the next outgoing record is ready
497 uint16_t version_out
;
500 * Record handler contexts.
503 const br_sslrec_in_class
*vtable
;
504 br_sslrec_in_cbc_context cbc
;
505 br_sslrec_gcm_context gcm
;
508 const br_sslrec_out_class
*vtable
;
509 br_sslrec_out_clear_context clear
;
510 br_sslrec_out_cbc_context cbc
;
511 br_sslrec_gcm_context gcm
;
515 * The "application data" flag. It is set when application data
516 * can be exchanged, cleared otherwise.
518 unsigned char application_data
;
523 br_hmac_drbg_context rng
;
525 int rng_os_rand_done
;
528 * Supported minimum and maximum versions, and cipher suites.
530 uint16_t version_min
;
531 uint16_t version_max
;
532 uint16_t suites_buf
[BR_MAX_CIPHER_SUITES
];
533 unsigned char suites_num
;
536 * For clients, the server name to send as a SNI extension. For
537 * servers, the name received in the SNI extension (if any).
539 char server_name
[256];
542 * "Security parameters". These are filled by the handshake
543 * handler, and used when switching encryption state.
545 unsigned char client_random
[32];
546 unsigned char server_random
[32];
548 unsigned char session_id[32];
549 unsigned char session_id_len;
551 uint16_t cipher_suite;
552 unsigned char master_secret[48];
554 br_ssl_session_parameters session
;
557 * ECDHE elements: curve and point from the peer. The server also
558 * uses that buffer for the point to send to the client.
560 unsigned char ecdhe_curve
;
561 unsigned char ecdhe_point
[133];
562 unsigned char ecdhe_point_len
;
565 * Secure renegotiation (RFC 5746): 'reneg' can be:
566 * 0 first handshake (server support is not known)
567 * 1 server does not support secure renegotiation
568 * 2 server supports secure renegotiation
570 * The saved_finished buffer contains the client and the
571 * server "Finished" values from the last handshake, in
572 * that order (12 bytes each).
575 unsigned char saved_finished
[24];
578 * Context variables for the handshake processor.
579 * The 'pad' must be large enough to accommodate an
580 * RSA-encrypted pre-master secret, or a RSA signature on
581 * key exchange parameters; since we want to support up to
582 * RSA-4096, this means at least 512 bytes.
583 * (Other pad usages require its length to be at least 256.)
588 const unsigned char *ip
;
590 uint32_t dp_stack
[32];
591 uint32_t rp_stack
[32];
592 unsigned char pad
[512];
593 unsigned char *hbuf_in
, *hbuf_out
, *saved_hbuf_out
;
594 size_t hlen_in
, hlen_out
;
595 void (*hsrun
)(void *ctx
);
598 * The 'action' value communicates OOB information between the
599 * engine and the handshake processor.
602 * 0 invocation triggered by I/O
603 * 1 invocation triggered by explicit close
604 * 2 invocation triggered by explicit renegotiation
606 unsigned char action
;
609 * State for alert messages. Value is either 0, or the value of
610 * the alert level byte (level is either 1 for warning, or 2 for
611 * fatal; we convert all other values to 'fatal').
616 * Closure flags. This flag is set when a close_notify has been
617 * received from the peer.
619 unsigned char close_received
;
622 * Multi-hasher for the handshake messages. The handshake handler
623 * is responsible for resetting it when appropriate.
625 br_multihash_context mhash
;
628 * Pointer to the X.509 engine. The engine is supposed to be
629 * already initialized. It is used to validate the peer's
632 const br_x509_class
**x509ctx
;
635 * Pointers to implementations; left to NULL for unsupported
636 * functions. For the raw hash functions, implementations are
637 * referenced from the multihasher (mhash field).
639 br_tls_prf_impl prf10
;
640 br_tls_prf_impl prf_sha256
;
641 br_tls_prf_impl prf_sha384
;
642 const br_block_cbcenc_class
*iaes_cbcenc
;
643 const br_block_cbcdec_class
*iaes_cbcdec
;
644 const br_block_ctr_class
*iaes_ctr
;
645 const br_block_cbcenc_class
*ides_cbcenc
;
646 const br_block_cbcdec_class
*ides_cbcdec
;
648 const br_sslrec_in_cbc_class
*icbc_in
;
649 const br_sslrec_out_cbc_class
*icbc_out
;
650 const br_sslrec_in_gcm_class
*igcm_in
;
651 const br_sslrec_out_gcm_class
*igcm_out
;
652 const br_ec_impl
*iec
;
654 } br_ssl_engine_context
;
657 * Set the minimum and maximum supported protocol versions.
660 br_ssl_engine_set_versions(br_ssl_engine_context
*cc
,
661 unsigned version_min
, unsigned version_max
)
663 cc
->version_min
= version_min
;
664 cc
->version_max
= version_max
;
668 * Set the list of cipher suites advertised by this context. The provided
669 * array is copied into the context. It is the caller responsibility
670 * to ensure that all provided suites will be supported by the context.
672 void br_ssl_engine_set_suites(br_ssl_engine_context
*cc
,
673 const uint16_t *suites
, size_t suites_num
);
676 * Set the X.509 engine. The context should be already initialized and
677 * ready to process a new chain.
680 br_ssl_engine_set_x509(br_ssl_engine_context
*cc
, const br_x509_class
**x509ctx
)
682 cc
->x509ctx
= x509ctx
;
686 * Set a hash function implementation (by ID).
689 br_ssl_engine_set_hash(br_ssl_engine_context
*ctx
,
690 int id
, const br_hash_class
*impl
)
692 br_multihash_setimpl(&ctx
->mhash
, id
, impl
);
696 * Get a hash function implementation (by ID).
698 static inline const br_hash_class
*
699 br_ssl_engine_get_hash(br_ssl_engine_context
*ctx
, int id
)
701 return br_multihash_getimpl(&ctx
->mhash
, id
);
705 * Set the PRF implementation (for TLS 1.0 and 1.1).
708 br_ssl_engine_set_prf10(br_ssl_engine_context
*cc
, br_tls_prf_impl impl
)
714 * Set the PRF implementation (for TLS 1.2, with SHA-256).
717 br_ssl_engine_set_prf_sha256(br_ssl_engine_context
*cc
, br_tls_prf_impl impl
)
719 cc
->prf_sha256
= impl
;
723 * Set the PRF implementation (for TLS 1.2, with SHA-384).
726 br_ssl_engine_set_prf_sha384(br_ssl_engine_context
*cc
, br_tls_prf_impl impl
)
728 cc
->prf_sha384
= impl
;
732 * Set the AES/CBC implementations.
735 br_ssl_engine_set_aes_cbc(br_ssl_engine_context
*cc
,
736 const br_block_cbcenc_class
*impl_enc
,
737 const br_block_cbcdec_class
*impl_dec
)
739 cc
->iaes_cbcenc
= impl_enc
;
740 cc
->iaes_cbcdec
= impl_dec
;
744 * Set the AES/CTR implementation.
747 br_ssl_engine_set_aes_ctr(br_ssl_engine_context
*cc
,
748 const br_block_ctr_class
*impl
)
754 * Set the 3DES/CBC implementations.
757 br_ssl_engine_set_des_cbc(br_ssl_engine_context
*cc
,
758 const br_block_cbcenc_class
*impl_enc
,
759 const br_block_cbcdec_class
*impl_dec
)
761 cc
->ides_cbcenc
= impl_enc
;
762 cc
->ides_cbcdec
= impl_dec
;
766 * Set the GHASH implementation (for GCM).
769 br_ssl_engine_set_ghash(br_ssl_engine_context
*cc
, br_ghash impl
)
775 * Set the CBC+HMAC record processor implementations.
778 br_ssl_engine_set_cbc(br_ssl_engine_context
*cc
,
779 const br_sslrec_in_cbc_class
*impl_in
,
780 const br_sslrec_out_cbc_class
*impl_out
)
782 cc
->icbc_in
= impl_in
;
783 cc
->icbc_out
= impl_out
;
787 * Set the GCM record processor implementations.
790 br_ssl_engine_set_gcm(br_ssl_engine_context
*cc
,
791 const br_sslrec_in_gcm_class
*impl_in
,
792 const br_sslrec_out_gcm_class
*impl_out
)
794 cc
->igcm_in
= impl_in
;
795 cc
->igcm_out
= impl_out
;
799 * Set the ECC core operations implementation. The 'iec' parameter
800 * points to the core EC code used for both ECDHE and ECDSA.
803 br_ssl_engine_set_ec(br_ssl_engine_context
*cc
, const br_ec_impl
*iec
)
809 * Set the I/O buffer for a SSL engine. Once this call has been made,
810 * br_ssl_client_reset() or br_ssl_server_reset() must be called before
813 * If 'bidi' is 1, then the buffer will be internally split to support
814 * concurrent input and output; otherwise, the caller will be responsible
815 * for reading all buffered incoming data before writing. The latter
816 * case makes support of HTTPS pipelining difficult, thus bidirectional
817 * buffering is recommended if the RAM can be spared.
819 * The BR_SSL_BUFSIZE_MONO and BR_SSL_BUFSIZE_BIDI macros yield optimal
820 * buffer sizes for the monodirectional and bidirectional cases,
821 * respectively. If using optimal sizes (or larger), then records with
822 * the maximum length supported by the TLS standard will be accepted
825 void br_ssl_engine_set_buffer(br_ssl_engine_context
*cc
,
826 void *iobuf
, size_t iobuf_len
, int bidi
);
829 * Set the I/O buffers for a SSL engine. This call sets two buffers, for
830 * concurrent input and output. The two buffers MUST be disjoint. Once
831 * this call has been made, br_ssl_client_reset() or
832 * br_ssl_server_reset() must be called before using the context.
834 * The BR_SSL_BUFSIZE_INPUT and BR_SSL_BUFSIZE_OUTPUT macros evaluate to
835 * optimal sizes for the input and output buffers, respectively. If
836 * using optimal sizes (or larger), then records with the maximum length
837 * supported by the TLS standard will be accepted and emitted.
839 void br_ssl_engine_set_buffers_bidi(br_ssl_engine_context
*cc
,
840 void *ibuf
, size_t ibuf_len
, void *obuf
, size_t obuf_len
);
843 * Inject some "initial entropy" in the context. This entropy will be added
844 * to what can be obtained from the underlying operating system, if that
847 * This function may be called several times; all injected entropy chunks
848 * are cumulatively mixed.
850 * If entropy gathering from the OS is supported and compiled in, then this
851 * step is optional. Otherwise, it is mandatory to inject randomness, and
852 * the caller MUST take care to push (as one or several successive calls)
853 * enough entropy to achieve cryptographic resistance (at least 80 bits,
854 * preferably 128 or more). The engine will report an error if no entropy
855 * was provided and none can be obtained from the OS.
857 * Take care that this function cannot assess the cryptographic quality of
858 * the provided bytes.
860 * In all generality, "entropy" must here be considered to mean "that
861 * which the attacker cannot predict". If your OS/architecture does not
862 * have a suitable source of randomness, then you can make do with the
863 * combination of a large enough secret value (possibly a copy of an
864 * asymmetric private key that you also store on the system) AND a
865 * non-repeating value (e.g. current time, provided that the local clock
866 * cannot be reset or altered by the attacker).
868 void br_ssl_engine_inject_entropy(br_ssl_engine_context
*cc
,
869 const void *data
, size_t len
);
872 * Get the "server name" in this engine. For clients, this is the name
873 * provided with br_ssl_client_reset(); for servers, this is the name
874 * received from the client as part of the ClientHello message. If there
875 * is no such name (e.g. the client did not send an SNI extension) then
876 * the returned string is empty (returned pointer points to a byte of
879 static inline const char *
880 br_ssl_engine_get_server_name(br_ssl_engine_context
*cc
)
882 return cc
->server_name
;
886 * An SSL engine (client or server) has, at any time, a state which is
887 * the combination of zero, one or more of these flags:
889 * BR_SSL_CLOSED engine is finished, no more I/O (until next reset)
890 * BR_SSL_SENDREC engine has some bytes to send to the peer
891 * BR_SSL_RECVREC engine expects some bytes from the peer
892 * BR_SSL_SENDAPP engine may receive application data to send (or flush)
893 * BR_SSL_RECVAPP engine has obtained some application data from the peer,
894 * that should be read by the caller
896 * If no flag at all is set (state value is 0), then the engine is not
897 * fully initialized yet.
899 * The BR_SSL_CLOSED flag is exclusive; when it is set, no other flag is set.
900 * To distinguish between a normal closure and an error, use
901 * br_ssl_engine_last_error().
903 * Generally speaking, BR_SSL_SENDREC and BR_SSL_SENDAPP are mutually
904 * exclusive: the input buffer, at any point, either accumulates
905 * plaintext data, or contains an assembled record that is being sent.
906 * Similarly, BR_SSL_RECVREC and BR_SSL_RECVAPP are mutually exclusive.
907 * This may change in a future library version.
910 #define BR_SSL_CLOSED 0x0001
911 #define BR_SSL_SENDREC 0x0002
912 #define BR_SSL_RECVREC 0x0004
913 #define BR_SSL_SENDAPP 0x0008
914 #define BR_SSL_RECVAPP 0x0010
917 * Get the current engine state.
919 unsigned br_ssl_engine_current_state(const br_ssl_engine_context
*cc
);
922 * Get the engine error indicator. This is BR_ERR_OK (0) if no error was
923 * encountered since the last call to br_ssl_client_reset() or
924 * br_ssl_server_reset(). Only these calls clear the error indicator.
927 br_ssl_engine_last_error(const br_ssl_engine_context
*cc
)
933 * There are four I/O operations, each identified by a symbolic name:
935 * sendapp inject application data in the engine
936 * recvapp retrieving application data from the engine
937 * sendrec sending records on the transport medium
938 * recvrec receiving records from the transport medium
940 * Terminology works thus: in a layered model where the SSL engine sits
941 * between the application and the network, "send" designates operations
942 * where bytes flow from application to network, and "recv" for the
943 * reverse operation. Application data (the plaintext that is to be
944 * conveyed through SSL) is "app", while encrypted records are "rec".
945 * Note that from the SSL engine point of view, "sendapp" and "recvrec"
946 * designate bytes that enter the engine ("inject" operation), while
947 * "recvapp" and "sendrec" designate bytes that exit the engine
948 * ("extract" operation).
950 * For the operation 'xxx', two functions are defined:
952 * br_ssl_engine_xxx_buf
953 * Returns a pointer and length to the buffer to use for that
954 * operation. '*len' is set to the number of bytes that may be read
955 * from the buffer (extract operation) or written to the buffer
956 * (inject operation). If no byte may be exchanged for that operation
957 * at that point, then '*len' is set to zero, and NULL is returned.
958 * The engine state is unmodified by this call.
960 * br_ssl_engine_xxx_ack
961 * Informs the engine that 'len' bytes have been read from the buffer
962 * (extract operation) or written to the buffer (inject operation).
963 * The 'len' value MUST NOT be zero. The 'len' value MUST NOT exceed
964 * that which was obtained from a preceeding br_ssl_engine_xxx_buf()
968 unsigned char *br_ssl_engine_sendapp_buf(
969 const br_ssl_engine_context
*cc
, size_t *len
);
970 void br_ssl_engine_sendapp_ack(br_ssl_engine_context
*cc
, size_t len
);
972 unsigned char *br_ssl_engine_recvapp_buf(
973 const br_ssl_engine_context
*cc
, size_t *len
);
974 void br_ssl_engine_recvapp_ack(br_ssl_engine_context
*cc
, size_t len
);
976 unsigned char *br_ssl_engine_sendrec_buf(
977 const br_ssl_engine_context
*cc
, size_t *len
);
978 void br_ssl_engine_sendrec_ack(br_ssl_engine_context
*cc
, size_t len
);
980 unsigned char *br_ssl_engine_recvrec_buf(
981 const br_ssl_engine_context
*cc
, size_t *len
);
982 void br_ssl_engine_recvrec_ack(br_ssl_engine_context
*cc
, size_t len
);
985 * If some application data has been buffered in the engine, then wrap
986 * it into a record and mark it for sending. If no application data has
987 * been buffered but the engine would be ready to accept some, AND the
988 * 'force' parameter is non-zero, then an empty record is assembled and
989 * marked for sending. In all other cases, this function does nothing.
991 * Empty records are technically legal, but not all existing SSL/TLS
992 * implementations support them. Empty records can be useful as a
993 * transparent "keep-alive" mechanism to maintain some low-level
996 void br_ssl_engine_flush(br_ssl_engine_context
*cc
, int force
);
999 * Close the context. If, at that point, the context is open and in
1000 * ready state, then a close_notify alert is assembled and marked for
1001 * sending. Otherwise, no such alert is assembled.
1003 void br_ssl_engine_close(br_ssl_engine_context
*cc
);
1006 * Initiate a renegotiation. If the engine is failed or closed, or if
1007 * the peer is known not to support secure renegotiation (RFC 5746),
1008 * then this function returns 0. Otherwise, this function returns 1 and
1009 * a renegotiation attempt is triggered, unless a handshake is already
1010 * taking place, in which case the call is ignored.
1012 int br_ssl_engine_renegotiate(br_ssl_engine_context
*cc
);
1015 * Context structure for a SSL client.
1019 * The encapsulated engine context.
1021 br_ssl_engine_context eng
;
1024 * Minimum ClientHello length; padding with an extension (RFC
1025 * 7685) is added if necessary to match at least that length.
1026 * Such padding is nominally unnecessary, but it has been used
1027 * to work around some server implementation bugs.
1029 uint16_t min_clienthello_len
;
1034 br_rsa_public irsapub
;
1035 br_rsa_pkcs1_vrfy irsavrfy
;
1036 br_ecdsa_vrfy iecdsa
;
1038 } br_ssl_client_context
;
1041 * Each br_ssl_client_init_xxx() function sets the list of supported
1042 * cipher suites and used implementations, as specified by the profile
1043 * name 'xxx'. Defined profile names are:
1045 * full all supported versions and suites; constant-time implementations
1046 * FIXME: add other profiles
1049 void br_ssl_client_init_full(br_ssl_client_context
*cc
,
1050 br_x509_minimal_context
*xc
,
1051 const br_x509_trust_anchor
*trust_anchors
, size_t trust_anchors_num
);
1054 * Clear the complete contents of a SSL client context, including the
1055 * reference to the configured buffer, implementations, cipher suites
1058 void br_ssl_client_zero(br_ssl_client_context
*cc
);
1061 * Set the RSA public-key operations implementation. This will be used
1062 * to encrypt the pre-master secret with the server's RSA public key
1063 * (RSA-encryption cipher suites only).
1066 br_ssl_client_set_rsapub(br_ssl_client_context
*cc
, br_rsa_public irsapub
)
1068 cc
->irsapub
= irsapub
;
1072 * Set the RSA signature verification implementation. This will be used
1073 * to verify the server's signature on its ServerKeyExchange message
1074 * (ECDHE_RSA cipher suites only).
1077 br_ssl_client_set_rsavrfy(br_ssl_client_context
*cc
, br_rsa_pkcs1_vrfy irsavrfy
)
1079 cc
->irsavrfy
= irsavrfy
;
1083 * Set the ECDSA implementation (signature verification). The ECC core
1084 * implementation must also have been set.
1087 br_ssl_client_set_ecdsa(br_ssl_client_context
*cc
, br_ecdsa_vrfy iecdsa
)
1089 cc
->iecdsa
= iecdsa
;
1093 * Set the minimum ClientHello length (RFC 7685 padding).
1096 br_ssl_client_set_min_clienthello_len(br_ssl_client_context
*cc
, uint16_t len
)
1098 cc
->min_clienthello_len
= len
;
1102 * Prepare or reset a client context for connecting with a server of
1103 * name 'server_name'. The 'server_name' parameter is used to fill the
1104 * SNI extension; if the parameter is NULL then no SNI extension will
1107 * If 'resume_session' is non-zero and the context was previously used
1108 * then the session parameters may be reused (depending on whether the
1109 * server previously sent a non-empty session ID, and accepts the session
1112 * On failure, the context is marked as failed, and this function
1113 * returns 0. A possible failure condition is when no initial entropy
1114 * was injected, and none could be obtained from the OS (either OS
1115 * randomness gathering is not supported, or it failed).
1117 int br_ssl_client_reset(br_ssl_client_context
*cc
,
1118 const char *server_name
, int resume_session
);
1121 * Forget any session in the context. This means that the next handshake
1122 * that uses this context will necessarily be a full handshake (this
1123 * applies both to new connections and to renegotiations).
1126 br_ssl_client_forget_session(br_ssl_client_context
*cc
)
1128 cc
->eng
.session
.session_id_len
= 0;
1132 * Type for a "translated cipher suite", as an array of 16-bit integers:
1133 * first element is the cipher suite identifier (as used on the wire),
1134 * and the second element is the concatenation of four 4-bit elements which
1135 * characterise the cipher suite contents. In most to least significant
1136 * order, these 4-bit elements are:
1138 * Bits 12 to 15: key exchange + server key type
1139 * 0 RSA RSA key exchange, key is RSA (encryption)
1140 * 1 ECDHE-RSA ECDHE key exchange, key is RSA (signature)
1141 * 2 ECDHE-ECDSA ECDHE key exchange, key is EC (signature)
1142 * 3 ECDH-RSA Key is EC (key exchange), cert is signed with RSA
1143 * 4 ECDH-ECDSA Key is EC (key exchange), cert is signed with ECDSA
1145 * Bits 8 to 11: symmetric encryption algorithm
1151 * 5 ChaCha20/Poly1305
1153 * Bits 4 to 7: MAC algorithm
1154 * 0 AEAD No dedicated MAC because encryption is AEAD
1155 * 2 HMAC/SHA-1 Value matches br_sha1_ID
1156 * 4 HMAC/SHA-256 Value matches br_sha256_ID
1157 * 5 HMAC/SHA-384 Value matches br_sha384_ID
1159 * Bits 0 to 3: hash function for PRF when used with TLS-1.2
1160 * 4 SHA-256 Value matches br_sha256_ID
1161 * 5 SHA-384 Value matches br_sha384_ID
1163 typedef uint16_t br_suite_translated
[2];
1165 #define BR_SSLKEYX_RSA 0
1166 #define BR_SSLKEYX_ECDHE_RSA 1
1167 #define BR_SSLKEYX_ECDHE_ECDSA 2
1168 #define BR_SSLKEYX_ECDH_RSA 3
1169 #define BR_SSLKEYX_ECDH_ECDSA 4
1171 #define BR_SSLENC_3DES_CBC 0
1172 #define BR_SSLENC_AES128_CBC 1
1173 #define BR_SSLENC_AES256_CBC 2
1174 #define BR_SSLENC_AES128_GCM 3
1175 #define BR_SSLENC_AES256_GCM 4
1176 #define BR_SSLENC_CHACHA20 5
1178 #define BR_SSLMAC_AEAD 0
1179 #define BR_SSLMAC_SHA1 br_sha1_ID
1180 #define BR_SSLMAC_SHA256 br_sha256_ID
1181 #define BR_SSLMAC_SHA384 br_sha384_ID
1183 #define BR_SSLPRF_SHA256 br_sha256_ID
1184 #define BR_SSLPRF_SHA384 br_sha384_ID
1187 * Pre-declaration for the SSL server context.
1189 typedef struct br_ssl_server_context_ br_ssl_server_context
;
1192 * Type for the server policy choices, taken after analysis of the client
1195 * cipher_suite Cipher suite to use.
1197 * hash_id Signature hash function identifier (hash function
1198 * to use for signing the ServerKeyExchange, when the
1199 * suite uses ECDHE).
1201 * chain The certificate chain to send (number of certificates
1202 * chain_len is in chain_length). The certificates are send "as is"
1203 * and shall be in standard SSL/TLS order (i.e. end-entity
1204 * first, each subsequent certificate signs the previous).
1207 uint16_t cipher_suite
;
1209 const br_x509_certificate
*chain
;
1211 } br_ssl_server_choices
;
1214 * Type for the certificate and private key handler on the server: an
1215 * object with the following methods:
1217 * choose Select the parameters for this connection (cipher suite,
1218 * certificate chain...). The selection is written into the
1219 * '*choices' structure. Returned value is 1 on success, or
1220 * 0 on error (an error here means that the handshake will
1221 * fail, and a handshake_failure alert will be sent to the
1224 * do_keyx Perform the server-side key exchange operation. Returned
1225 * value is 1 on success, 0 on error (see below). This is
1226 * called only when the selected cipher suite calls for a
1227 * RSA or ECDH key exchange involving the server key.
1229 * do_sign Perform the server-side signature operation. Returned
1230 * value is the signature length, or 0 on error (see below).
1231 * This is called only when the selected cipher suite calls
1232 * for an ECDHE key exchange, signed by the server with its key.
1235 * The do_keyx() method shall apply the following semantics:
1237 * -- For RSA key exchange, it shall decrypt the incoming data along
1238 * the rules of PKCS#1 v1.5. The method must verify the proper padding
1239 * and also that the decrypted message length is exactly 48 bytes.
1240 * IMPORTANT: these operations MUST be constant-time (or adequatly blinded).
1241 * The decrypted message is written in the first 48 bytes of data[]. The
1242 * caller makes sure that the data[] buffer is large enough, and that 'len'
1243 * is at least 59 bytes.
1245 * -- For ECDH key exchange, the provided data is an EC point (uncompressed
1246 * format); the method shall multiply that point with the server private
1247 * key, and write the X coordinate of the resulting point in the data[]
1248 * buffer, starting at offset 1 (so if the method produces a compressed or
1249 * uncompressed point, form offset 0, then everything is fine).
1251 * In both cases, returned value is 1 on success, 0 on error.
1254 * The do_sign() method shall compute the signature on the hash value
1255 * provided in the data[] buffer. The 'hv_len' value contains the hash
1256 * value length, while the 'len' parameter is the total size of the
1257 * buffer. The method must verify that the signature length is no more
1258 * than 'len' bytes, and report an error otherwise.
1260 * The hash identifier is either 0 for the MD5+SHA-1 method in TLS-1.0 and
1261 * 1.1, or a non-zero hash function identifier in TLS-1.2 and later. In
1262 * the MD5+SHA-1 method, the hash value has length 36 bytes and there is
1263 * no hash function identifying header to add in the padding.
1265 * Returned value is the signature length (in bytes). On error, this method
1268 typedef struct br_ssl_server_policy_class_ br_ssl_server_policy_class
;
1269 struct br_ssl_server_policy_class_
{
1270 size_t context_size
;
1271 int (*choose
)(const br_ssl_server_policy_class
**pctx
,
1272 const br_ssl_server_context
*cc
,
1273 br_ssl_server_choices
*choices
);
1274 uint32_t (*do_keyx
)(const br_ssl_server_policy_class
**pctx
,
1275 unsigned char *data
, size_t len
);
1276 size_t (*do_sign
)(const br_ssl_server_policy_class
**pctx
,
1277 int hash_id
, size_t hv_len
, unsigned char *data
, size_t len
);
1281 * A single-chain RSA policy handler, that always uses a single chain and
1282 * a RSA key. It may be restricted to do only signatures or only key
1286 const br_ssl_server_policy_class
*vtable
;
1287 const br_x509_certificate
*chain
;
1289 const br_rsa_private_key
*sk
;
1290 unsigned allowed_usages
;
1291 br_rsa_private irsacore
;
1292 br_rsa_pkcs1_sign irsasign
;
1293 } br_ssl_server_policy_rsa_context
;
1296 * A single-chain EC policy handler, that always uses a single chain and
1297 * an EC key. It may be restricted to do only signatures or only key
1301 const br_ssl_server_policy_class
*vtable
;
1302 const br_x509_certificate
*chain
;
1304 const br_ec_private_key
*sk
;
1305 unsigned allowed_usages
;
1306 unsigned cert_issuer_key_type
;
1307 const br_multihash_context
*mhash
;
1308 const br_ec_impl
*iec
;
1309 br_ecdsa_sign iecdsa
;
1310 } br_ssl_server_policy_ec_context
;
1313 * Class type for a session parameter cache.
1315 * save Record session parameters. The session ID has been randomly
1316 * generated, and the session ID length is always 32 bytes.
1317 * The method shall copy the provided information (the structure
1320 * load Find session parameters by ID. The session ID is in the relevant
1321 * field in the '*params' structure, and has always length exactly
1322 * 32 bytes. The method shall fill in the other field with the
1323 * session data, if found. Returned value is 1 when the session was
1324 * found, 0 otherwise.
1326 * Note that the requesting server context is provided. Implementations
1327 * may used some of the resources of that context, e.g. random number
1328 * generator or implementations of some cryptographic algorithms.
1330 typedef struct br_ssl_session_cache_class_ br_ssl_session_cache_class
;
1331 struct br_ssl_session_cache_class_
{
1332 size_t context_size
;
1333 void (*save
)(const br_ssl_session_cache_class
**ctx
,
1334 br_ssl_server_context
*server_ctx
,
1335 const br_ssl_session_parameters
*params
);
1336 int (*load
)(const br_ssl_session_cache_class
**ctx
,
1337 br_ssl_server_context
*server_ctx
,
1338 br_ssl_session_parameters
*params
);
1342 * Context for a very basic cache system that uses a linked list, managed
1343 * with an LRU algorithm (when the cache is full and a new set of parameters
1344 * must be saved, the least recently used entry is evicted). The storage
1345 * buffer is externally provided. Internally, an index tree is used to
1346 * speed up operations.
1349 const br_ssl_session_cache_class
*vtable
;
1350 unsigned char *store
;
1351 size_t store_len
, store_ptr
;
1352 unsigned char index_key
[32];
1353 const br_hash_class
*hash
;
1355 uint32_t head
, tail
, root
;
1356 } br_ssl_session_cache_lru
;
1359 * Initialise a LRU session cache with the provided storage space.
1361 void br_ssl_session_cache_lru_init(br_ssl_session_cache_lru
*cc
,
1362 unsigned char *store
, size_t store_len
);
1365 * Context structure for a SSL server.
1367 struct br_ssl_server_context_
{
1369 * The encapsulated engine context.
1371 br_ssl_engine_context eng
;
1379 * Maximum version from the client.
1381 uint16_t client_max_version
;
1386 const br_ssl_session_cache_class
**cache_vtable
;
1389 * Translated cipher suites supported by the client. The list
1390 * is trimmed to include only the cipher suites that the
1391 * server also supports; they are in the same order as in the
1394 br_suite_translated client_suites
[BR_MAX_CIPHER_SUITES
];
1395 unsigned char client_suites_num
;
1398 * Hash functions supported by the client, with ECDSA and RSA
1399 * (bit mask). For hash function with id 'x', set bit index is
1400 * x for RSA, x+8 for ECDSA.
1405 * Curves supported by the client (bit mask, for named curves).
1410 * Context for chain handler.
1412 const br_ssl_server_policy_class
**policy_vtable
;
1413 const br_x509_certificate
*chain
;
1415 const unsigned char *cert_cur
;
1417 unsigned char sign_hash_id
;
1420 * For the core handlers, thus avoiding (in most cases) the
1421 * need for an externally provided policy context.
1424 const br_ssl_server_policy_class
*vtable
;
1425 br_ssl_server_policy_rsa_context single_rsa
;
1426 br_ssl_server_policy_ec_context single_ec
;
1430 * Buffer for the ECDHE private key.
1432 unsigned char ecdhe_key
[70];
1433 size_t ecdhe_key_len
;
1436 * Server-specific implementations.
1441 * Get currently defined server behavioural flags.
1443 static inline uint32_t
1444 br_ssl_server_get_flags(br_ssl_server_context
*cc
)
1450 * Set all server flags. Flags which are not in the 'flags' argument
1454 br_ssl_server_set_all_flags(br_ssl_server_context
*cc
, uint32_t flags
)
1460 * Add some server flags. The provided flags are set in the server context,
1461 * but other flags are untouched.
1464 br_ssl_server_add_flags(br_ssl_server_context
*cc
, uint32_t flags
)
1470 * Remove some server flags. The provided flags are cleared from the
1471 * server context, but other flags are untouched.
1474 br_ssl_server_remove_flags(br_ssl_server_context
*cc
, uint32_t flags
)
1476 cc
->flags
&= ~flags
;
1480 * If this flag is set, then the server will enforce its own cipher suite
1481 * preference order; otherwise, it follows the client preferences.
1483 #define BR_OPT_ENFORCE_SERVER_PREFERENCES ((uint32_t)1 << 0)
1486 * Each br_ssl_server_init_xxx() function sets the list of supported
1487 * cipher suites and used implementations, as specified by the profile
1488 * name 'xxx'. Defined profile names are:
1490 * full_rsa all supported algorithm, server key type is RSA
1491 * full_ec all supported algorithm, server key type is EC
1492 * FIXME: add other profiles
1494 * Naming scheme for "minimal" profiles: min123
1496 * -- character 1: key exchange
1502 * -- character 2: version / PRF
1503 * 0 = TLS 1.0 / 1.1 with MD5+SHA-1
1504 * 2 = TLS 1.2 with SHA-256
1505 * 3 = TLS 1.2 with SHA-384
1506 * -- character 3: encryption
1512 void br_ssl_server_init_full_rsa(br_ssl_server_context
*cc
,
1513 const br_x509_certificate
*chain
, size_t chain_len
,
1514 const br_rsa_private_key
*sk
);
1516 void br_ssl_server_init_full_ec(br_ssl_server_context
*cc
,
1517 const br_x509_certificate
*chain
, size_t chain_len
,
1518 unsigned cert_issuer_key_type
, const br_ec_private_key
*sk
);
1520 void br_ssl_server_init_minr2g(br_ssl_server_context
*cc
,
1521 const br_x509_certificate
*chain
, size_t chain_len
,
1522 const br_rsa_private_key
*sk
);
1523 void br_ssl_server_init_mine2g(br_ssl_server_context
*cc
,
1524 const br_x509_certificate
*chain
, size_t chain_len
,
1525 const br_rsa_private_key
*sk
);
1526 void br_ssl_server_init_minf2g(br_ssl_server_context
*cc
,
1527 const br_x509_certificate
*chain
, size_t chain_len
,
1528 const br_ec_private_key
*sk
);
1529 void br_ssl_server_init_minu2g(br_ssl_server_context
*cc
,
1530 const br_x509_certificate
*chain
, size_t chain_len
,
1531 const br_ec_private_key
*sk
);
1532 void br_ssl_server_init_minv2g(br_ssl_server_context
*cc
,
1533 const br_x509_certificate
*chain
, size_t chain_len
,
1534 const br_ec_private_key
*sk
);
1537 * Get the supported client suites. The returned array is ordered by
1538 * client or server preferences, depending on the relevant flag.
1540 static inline const br_suite_translated
*
1541 br_ssl_server_get_client_suites(const br_ssl_server_context
*cc
, size_t *num
)
1543 *num
= cc
->client_suites_num
;
1544 return cc
->client_suites
;
1548 * Get the hash functions supported by the client. This is a field of
1549 * bits: for hash function of ID x, bit x is set if the hash function
1550 * is supported in RSA signatures, 8+x if it is supported with ECDSA.
1552 static inline uint16_t
1553 br_ssl_server_get_client_hashes(const br_ssl_server_context
*cc
)
1559 * Get the elliptic curves supported by the client. This is a bit field
1560 * (bit x is set if curve of ID x is supported).
1562 static inline uint32_t
1563 br_ssl_server_get_client_curves(const br_ssl_server_context
*cc
)
1569 * Clear the complete contents of a SSL server context, including the
1570 * reference to the configured buffer, implementations, cipher suites
1573 void br_ssl_server_zero(br_ssl_server_context
*cc
);
1576 * Set an externally provided policy context.
1579 br_ssl_server_set_policy(br_ssl_server_context
*cc
,
1580 const br_ssl_server_policy_class
**pctx
)
1582 cc
->policy_vtable
= pctx
;
1586 * Set the server certificate chain and key (single RSA case).
1587 * The 'allowed_usages' is a combination of usages, namely
1588 * BR_KEYTYPE_KEYX and/or BR_KEYTYPE_SIGN.
1590 void br_ssl_server_set_single_rsa(br_ssl_server_context
*cc
,
1591 const br_x509_certificate
*chain
, size_t chain_length
,
1592 const br_rsa_private_key
*sk
, unsigned allowed_usages
,
1593 br_rsa_private irsacore
, br_rsa_pkcs1_sign irsasign
);
1596 * Set the server certificate chain and key (single EC case).
1597 * The 'allowed_usages' is a combination of usages, namely
1598 * BR_KEYTYPE_KEYX and/or BR_KEYTYPE_SIGN.
1600 void br_ssl_server_set_single_ec(br_ssl_server_context
*cc
,
1601 const br_x509_certificate
*chain
, size_t chain_length
,
1602 const br_ec_private_key
*sk
, unsigned allowed_usages
,
1603 unsigned cert_issuer_key_type
,
1604 const br_ec_impl
*iec
, br_ecdsa_sign iecdsa
);
1607 * Configure the server context to use the provided cache for session
1611 br_ssl_server_set_cache(br_ssl_server_context
*cc
,
1612 const br_ssl_session_cache_class
**vtable
)
1614 cc
->cache_vtable
= vtable
;
1618 * Prepare or reset a server context for handling an incoming client.
1620 int br_ssl_server_reset(br_ssl_server_context
*cc
);
1622 /* ===================================================================== */
1625 * Context for the simplified I/O context. The transport medium is accessed
1626 * through the low_read() and low_write() callback functions, each with
1627 * its own opaque context pointer.
1629 * low_read() read some bytes, at most 'len' bytes, into data[]. The
1630 * returned value is the number of read bytes, or -1 on error.
1631 * The 'len' parameter is guaranteed never to exceed 20000,
1632 * so the length always fits in an 'int' on all platforms.
1634 * low_write() write up to 'len' bytes, to be read from data[]. The
1635 * returned value is the number of written bytes, or -1 on
1636 * error. The 'len' parameter is guaranteed never to exceed
1637 * 20000, so the length always fits in an 'int' on all
1640 * A socket closure (if the transport medium is a socket) should be reported
1641 * as an error (-1). The callbacks shall endeavour to block until at least
1642 * one byte can be read or written; a callback returning 0 at times is
1643 * acceptable, but this normally leads to the callback being immediately
1644 * called again, so the callback should at least always try to block for
1645 * some time if no I/O can take place.
1647 * The SSL engine naturally applies some buffering, so the callbacks need
1648 * not apply buffers of their own.
1651 br_ssl_engine_context
*engine
;
1652 int (*low_read
)(void *read_context
,
1653 unsigned char *data
, size_t len
);
1655 int (*low_write
)(void *write_context
,
1656 const unsigned char *data
, size_t len
);
1657 void *write_context
;
1661 * Initialise a simplified I/O context over the provided engine and
1664 void br_sslio_init(br_sslio_context
*ctx
,
1665 br_ssl_engine_context
*engine
,
1666 int (*low_read
)(void *read_context
,
1667 unsigned char *data
, size_t len
),
1669 int (*low_write
)(void *write_context
,
1670 const unsigned char *data
, size_t len
),
1671 void *write_context
);
1674 * Read some application data from a SSL connection. This call returns
1675 * only when at least one byte has been obtained. Returned value is
1676 * the number of bytes read, or -1 on error. The number of bytes
1677 * always fits on an 'int' (data from a single SSL/TLS record is
1680 * On error or SSL closure, this function returns -1. The caller should
1681 * inspect the error status on the SSL engine to distinguish between
1682 * normal closure and error.
1684 int br_sslio_read(br_sslio_context
*cc
, void *dst
, size_t len
);
1687 * Read some application data from a SSL connection. This call returns
1688 * only when ALL requested bytes have been read. Returned value is 0
1689 * on success, -1 on error. A normal SSL closure before that many bytes
1690 * are obtained is reported as an error by this function.
1692 int br_sslio_read_all(br_sslio_context
*cc
, void *dst
, size_t len
);
1695 * Write some application data onto a SSL connection. This call returns
1696 * only when at least one byte had been written onto the connection (but
1697 * not necessarily flushed). Returned value is the number of written
1698 * bytes, or -1 on error (error conditions include a closed connection).
1699 * It is guaranteed that the number of bytes written by such a call will
1700 * fit in an 'int' on all architectures.
1702 * Note that some written bytes may be buffered; use br_sslio_flush()
1703 * to make sure that the data is sent to the transport stream.
1705 int br_sslio_write(br_sslio_context
*cc
, const void *src
, size_t len
);
1708 * Write some application data onto a SSL connection. This call returns
1709 * only when ALL the bytes have been written onto the connection (but
1710 * not necessarily flushed). Returned value is 0 on success, -1 on error.
1712 * Note that some written bytes may be buffered; use br_sslio_flush()
1713 * to make sure that the data is sent to the transport stream.
1715 int br_sslio_write_all(br_sslio_context
*cc
, const void *src
, size_t len
);
1718 * Make sure that any buffered application data in the provided context
1719 * get packed up and sent unto the low_write() callback method. If that
1720 * callback method represents a buffered system, it is up to the caller
1721 * to then "flush" that system too.
1723 * Returned value is 0 on success, -1 on error.
1725 int br_sslio_flush(br_sslio_context
*cc
);
1728 * Perform a SSL close. This implies sending a close_notify, and reading
1729 * the response from the server. Returned value is 0 on success, -1 on
1732 int br_sslio_close(br_sslio_context
*cc
);
1734 /* ===================================================================== */
1737 * Symbolic constants for cipher suites.
1741 #define BR_TLS_NULL_WITH_NULL_NULL 0x0000
1742 #define BR_TLS_RSA_WITH_NULL_MD5 0x0001
1743 #define BR_TLS_RSA_WITH_NULL_SHA 0x0002
1744 #define BR_TLS_RSA_WITH_NULL_SHA256 0x003B
1745 #define BR_TLS_RSA_WITH_RC4_128_MD5 0x0004
1746 #define BR_TLS_RSA_WITH_RC4_128_SHA 0x0005
1747 #define BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA 0x000A
1748 #define BR_TLS_RSA_WITH_AES_128_CBC_SHA 0x002F
1749 #define BR_TLS_RSA_WITH_AES_256_CBC_SHA 0x0035
1750 #define BR_TLS_RSA_WITH_AES_128_CBC_SHA256 0x003C
1751 #define BR_TLS_RSA_WITH_AES_256_CBC_SHA256 0x003D
1752 #define BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 0x000D
1753 #define BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 0x0010
1754 #define BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 0x0013
1755 #define BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 0x0016
1756 #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA 0x0030
1757 #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA 0x0031
1758 #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA 0x0032
1759 #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA 0x0033
1760 #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA 0x0036
1761 #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA 0x0037
1762 #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA 0x0038
1763 #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x0039
1764 #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256 0x003E
1765 #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256 0x003F
1766 #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 0x0040
1767 #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 0x0067
1768 #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256 0x0068
1769 #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256 0x0069
1770 #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 0x006A
1771 #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 0x006B
1772 #define BR_TLS_DH_anon_WITH_RC4_128_MD5 0x0018
1773 #define BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 0x001B
1774 #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA 0x0034
1775 #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA 0x003A
1776 #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256 0x006C
1777 #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256 0x006D
1780 #define BR_TLS_ECDH_ECDSA_WITH_NULL_SHA 0xC001
1781 #define BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0xC002
1782 #define BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC003
1783 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0xC004
1784 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0xC005
1785 #define BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA 0xC006
1786 #define BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0xC007
1787 #define BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC008
1788 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0xC009
1789 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0xC00A
1790 #define BR_TLS_ECDH_RSA_WITH_NULL_SHA 0xC00B
1791 #define BR_TLS_ECDH_RSA_WITH_RC4_128_SHA 0xC00C
1792 #define BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0xC00D
1793 #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0xC00E
1794 #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0xC00F
1795 #define BR_TLS_ECDHE_RSA_WITH_NULL_SHA 0xC010
1796 #define BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA 0xC011
1797 #define BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0xC012
1798 #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0xC013
1799 #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC014
1800 #define BR_TLS_ECDH_anon_WITH_NULL_SHA 0xC015
1801 #define BR_TLS_ECDH_anon_WITH_RC4_128_SHA 0xC016
1802 #define BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 0xC017
1803 #define BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA 0xC018
1804 #define BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA 0xC019
1807 #define BR_TLS_RSA_WITH_AES_128_GCM_SHA256 0x009C
1808 #define BR_TLS_RSA_WITH_AES_256_GCM_SHA384 0x009D
1809 #define BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 0x009E
1810 #define BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 0x009F
1811 #define BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256 0x00A0
1812 #define BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384 0x00A1
1813 #define BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 0x00A2
1814 #define BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 0x00A3
1815 #define BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256 0x00A4
1816 #define BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384 0x00A5
1817 #define BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256 0x00A6
1818 #define BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384 0x00A7
1821 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023
1822 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024
1823 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC025
1824 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0xC026
1825 #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0xC027
1826 #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC028
1827 #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0xC029
1828 #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0xC02A
1829 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B
1830 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C
1831 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 0xC02D
1832 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 0xC02E
1833 #define BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC02F
1834 #define BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xC030
1835 #define BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 0xC031
1836 #define BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 0xC032
1839 #define BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8
1840 #define BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9
1841 #define BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCAA
1842 #define BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAB
1843 #define BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAC
1844 #define BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAD
1845 #define BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAE
1848 * Symbolic constants for alerts.
1850 #define BR_ALERT_CLOSE_NOTIFY 0
1851 #define BR_ALERT_UNEXPECTED_MESSAGE 10
1852 #define BR_ALERT_BAD_RECORD_MAC 20
1853 #define BR_ALERT_RECORD_OVERFLOW 22
1854 #define BR_ALERT_DECOMPRESSION_FAILURE 30
1855 #define BR_ALERT_HANDSHAKE_FAILURE 40
1856 #define BR_ALERT_BAD_CERTIFICATE 42
1857 #define BR_ALERT_UNSUPPORTED_CERTIFICATE 43
1858 #define BR_ALERT_CERTIFICATE_REVOKED 44
1859 #define BR_ALERT_CERTIFICATE_EXPIRED 45
1860 #define BR_ALERT_CERTIFICATE_UNKNOWN 46
1861 #define BR_ALERT_ILLEGAL_PARAMETER 47
1862 #define BR_ALERT_UNKNOWN_CA 48
1863 #define BR_ALERT_ACCESS_DENIED 49
1864 #define BR_ALERT_DECODE_ERROR 50
1865 #define BR_ALERT_DECRYPT_ERROR 51
1866 #define BR_ALERT_PROTOCOL_VERSION 70
1867 #define BR_ALERT_INSUFFICIENT_SECURITY 71
1868 #define BR_ALERT_INTERNAL_ERROR 80
1869 #define BR_ALERT_USER_CANCELED 90
1870 #define BR_ALERT_NO_RENEGOTIATION 100
1871 #define BR_ALERT_UNSUPPORTED_EXTENSION 110