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];
583 * Context variables for the handshake processor.
584 * The 'pad' must be large enough to accommodate an
585 * RSA-encrypted pre-master secret, or a RSA signature on
586 * key exchange parameters; since we want to support up to
587 * RSA-4096, this means at least 512 bytes.
588 * (Other pad usages require its length to be at least 256.)
593 const unsigned char *ip
;
595 uint32_t dp_stack
[32];
596 uint32_t rp_stack
[32];
597 unsigned char pad
[512];
598 unsigned char *hbuf_in
, *hbuf_out
, *saved_hbuf_out
;
599 size_t hlen_in
, hlen_out
;
600 void (*hsrun
)(void *ctx
);
603 * The 'action' value communicates OOB information between the
604 * engine and the handshake processor.
607 * 0 invocation triggered by I/O
608 * 1 invocation triggered by explicit close
609 * 2 invocation triggered by explicit renegotiation
611 unsigned char action
;
614 * State for alert messages. Value is either 0, or the value of
615 * the alert level byte (level is either 1 for warning, or 2 for
616 * fatal; we convert all other values to 'fatal').
621 * Closure flags. This flag is set when a close_notify has been
622 * received from the peer.
624 unsigned char close_received
;
627 * Multi-hasher for the handshake messages. The handshake handler
628 * is responsible for resetting it when appropriate.
630 br_multihash_context mhash
;
633 * Pointer to the X.509 engine. The engine is supposed to be
634 * already initialized. It is used to validate the peer's
637 const br_x509_class
**x509ctx
;
640 * Pointers to implementations; left to NULL for unsupported
641 * functions. For the raw hash functions, implementations are
642 * referenced from the multihasher (mhash field).
644 br_tls_prf_impl prf10
;
645 br_tls_prf_impl prf_sha256
;
646 br_tls_prf_impl prf_sha384
;
647 const br_block_cbcenc_class
*iaes_cbcenc
;
648 const br_block_cbcdec_class
*iaes_cbcdec
;
649 const br_block_ctr_class
*iaes_ctr
;
650 const br_block_cbcenc_class
*ides_cbcenc
;
651 const br_block_cbcdec_class
*ides_cbcdec
;
653 const br_sslrec_in_cbc_class
*icbc_in
;
654 const br_sslrec_out_cbc_class
*icbc_out
;
655 const br_sslrec_in_gcm_class
*igcm_in
;
656 const br_sslrec_out_gcm_class
*igcm_out
;
657 const br_ec_impl
*iec
;
659 } br_ssl_engine_context
;
662 * Get currently defined engine behavioural flags.
664 static inline uint32_t
665 br_ssl_engine_get_flags(br_ssl_engine_context
*cc
)
671 * Set all engine flags. Flags which are not in the 'flags' argument
675 br_ssl_engine_set_all_flags(br_ssl_engine_context
*cc
, uint32_t flags
)
681 * Add some engine flags. The provided flags are set in the engine context,
682 * but other flags are untouched.
685 br_ssl_engine_add_flags(br_ssl_engine_context
*cc
, uint32_t flags
)
691 * Remove some engine flags. The provided flags are cleared from the
692 * engine context, but other flags are untouched.
695 br_ssl_engine_remove_flags(br_ssl_engine_context
*cc
, uint32_t flags
)
701 * Set the minimum and maximum supported protocol versions.
704 br_ssl_engine_set_versions(br_ssl_engine_context
*cc
,
705 unsigned version_min
, unsigned version_max
)
707 cc
->version_min
= version_min
;
708 cc
->version_max
= version_max
;
712 * Set the list of cipher suites advertised by this context. The provided
713 * array is copied into the context. It is the caller responsibility
714 * to ensure that all provided suites will be supported by the context.
716 void br_ssl_engine_set_suites(br_ssl_engine_context
*cc
,
717 const uint16_t *suites
, size_t suites_num
);
720 * Set the X.509 engine. The context should be already initialized and
721 * ready to process a new chain.
724 br_ssl_engine_set_x509(br_ssl_engine_context
*cc
, const br_x509_class
**x509ctx
)
726 cc
->x509ctx
= x509ctx
;
730 * Set a hash function implementation (by ID).
733 br_ssl_engine_set_hash(br_ssl_engine_context
*ctx
,
734 int id
, const br_hash_class
*impl
)
736 br_multihash_setimpl(&ctx
->mhash
, id
, impl
);
740 * Get a hash function implementation (by ID).
742 static inline const br_hash_class
*
743 br_ssl_engine_get_hash(br_ssl_engine_context
*ctx
, int id
)
745 return br_multihash_getimpl(&ctx
->mhash
, id
);
749 * Set the PRF implementation (for TLS 1.0 and 1.1).
752 br_ssl_engine_set_prf10(br_ssl_engine_context
*cc
, br_tls_prf_impl impl
)
758 * Set the PRF implementation (for TLS 1.2, with SHA-256).
761 br_ssl_engine_set_prf_sha256(br_ssl_engine_context
*cc
, br_tls_prf_impl impl
)
763 cc
->prf_sha256
= impl
;
767 * Set the PRF implementation (for TLS 1.2, with SHA-384).
770 br_ssl_engine_set_prf_sha384(br_ssl_engine_context
*cc
, br_tls_prf_impl impl
)
772 cc
->prf_sha384
= impl
;
776 * Set the AES/CBC implementations.
779 br_ssl_engine_set_aes_cbc(br_ssl_engine_context
*cc
,
780 const br_block_cbcenc_class
*impl_enc
,
781 const br_block_cbcdec_class
*impl_dec
)
783 cc
->iaes_cbcenc
= impl_enc
;
784 cc
->iaes_cbcdec
= impl_dec
;
788 * Set the AES/CTR implementation.
791 br_ssl_engine_set_aes_ctr(br_ssl_engine_context
*cc
,
792 const br_block_ctr_class
*impl
)
798 * Set the 3DES/CBC implementations.
801 br_ssl_engine_set_des_cbc(br_ssl_engine_context
*cc
,
802 const br_block_cbcenc_class
*impl_enc
,
803 const br_block_cbcdec_class
*impl_dec
)
805 cc
->ides_cbcenc
= impl_enc
;
806 cc
->ides_cbcdec
= impl_dec
;
810 * Set the GHASH implementation (for GCM).
813 br_ssl_engine_set_ghash(br_ssl_engine_context
*cc
, br_ghash impl
)
819 * Set the CBC+HMAC record processor implementations.
822 br_ssl_engine_set_cbc(br_ssl_engine_context
*cc
,
823 const br_sslrec_in_cbc_class
*impl_in
,
824 const br_sslrec_out_cbc_class
*impl_out
)
826 cc
->icbc_in
= impl_in
;
827 cc
->icbc_out
= impl_out
;
831 * Set the GCM record processor implementations.
834 br_ssl_engine_set_gcm(br_ssl_engine_context
*cc
,
835 const br_sslrec_in_gcm_class
*impl_in
,
836 const br_sslrec_out_gcm_class
*impl_out
)
838 cc
->igcm_in
= impl_in
;
839 cc
->igcm_out
= impl_out
;
843 * Set the ECC core operations implementation. The 'iec' parameter
844 * points to the core EC code used for both ECDHE and ECDSA.
847 br_ssl_engine_set_ec(br_ssl_engine_context
*cc
, const br_ec_impl
*iec
)
853 * Set the I/O buffer for a SSL engine. Once this call has been made,
854 * br_ssl_client_reset() or br_ssl_server_reset() must be called before
857 * If 'bidi' is 1, then the buffer will be internally split to support
858 * concurrent input and output; otherwise, the caller will be responsible
859 * for reading all buffered incoming data before writing. The latter
860 * case makes support of HTTPS pipelining difficult, thus bidirectional
861 * buffering is recommended if the RAM can be spared.
863 * The BR_SSL_BUFSIZE_MONO and BR_SSL_BUFSIZE_BIDI macros yield optimal
864 * buffer sizes for the monodirectional and bidirectional cases,
865 * respectively. If using optimal sizes (or larger), then records with
866 * the maximum length supported by the TLS standard will be accepted
869 void br_ssl_engine_set_buffer(br_ssl_engine_context
*cc
,
870 void *iobuf
, size_t iobuf_len
, int bidi
);
873 * Set the I/O buffers for a SSL engine. This call sets two buffers, for
874 * concurrent input and output. The two buffers MUST be disjoint. Once
875 * this call has been made, br_ssl_client_reset() or
876 * br_ssl_server_reset() must be called before using the context.
878 * The BR_SSL_BUFSIZE_INPUT and BR_SSL_BUFSIZE_OUTPUT macros evaluate to
879 * optimal sizes for the input and output buffers, respectively. If
880 * using optimal sizes (or larger), then records with the maximum length
881 * supported by the TLS standard will be accepted and emitted.
883 void br_ssl_engine_set_buffers_bidi(br_ssl_engine_context
*cc
,
884 void *ibuf
, size_t ibuf_len
, void *obuf
, size_t obuf_len
);
887 * Inject some "initial entropy" in the context. This entropy will be added
888 * to what can be obtained from the underlying operating system, if that
891 * This function may be called several times; all injected entropy chunks
892 * are cumulatively mixed.
894 * If entropy gathering from the OS is supported and compiled in, then this
895 * step is optional. Otherwise, it is mandatory to inject randomness, and
896 * the caller MUST take care to push (as one or several successive calls)
897 * enough entropy to achieve cryptographic resistance (at least 80 bits,
898 * preferably 128 or more). The engine will report an error if no entropy
899 * was provided and none can be obtained from the OS.
901 * Take care that this function cannot assess the cryptographic quality of
902 * the provided bytes.
904 * In all generality, "entropy" must here be considered to mean "that
905 * which the attacker cannot predict". If your OS/architecture does not
906 * have a suitable source of randomness, then you can make do with the
907 * combination of a large enough secret value (possibly a copy of an
908 * asymmetric private key that you also store on the system) AND a
909 * non-repeating value (e.g. current time, provided that the local clock
910 * cannot be reset or altered by the attacker).
912 void br_ssl_engine_inject_entropy(br_ssl_engine_context
*cc
,
913 const void *data
, size_t len
);
916 * Get the "server name" in this engine. For clients, this is the name
917 * provided with br_ssl_client_reset(); for servers, this is the name
918 * received from the client as part of the ClientHello message. If there
919 * is no such name (e.g. the client did not send an SNI extension) then
920 * the returned string is empty (returned pointer points to a byte of
923 static inline const char *
924 br_ssl_engine_get_server_name(br_ssl_engine_context
*cc
)
926 return cc
->server_name
;
930 * An SSL engine (client or server) has, at any time, a state which is
931 * the combination of zero, one or more of these flags:
933 * BR_SSL_CLOSED engine is finished, no more I/O (until next reset)
934 * BR_SSL_SENDREC engine has some bytes to send to the peer
935 * BR_SSL_RECVREC engine expects some bytes from the peer
936 * BR_SSL_SENDAPP engine may receive application data to send (or flush)
937 * BR_SSL_RECVAPP engine has obtained some application data from the peer,
938 * that should be read by the caller
940 * If no flag at all is set (state value is 0), then the engine is not
941 * fully initialized yet.
943 * The BR_SSL_CLOSED flag is exclusive; when it is set, no other flag is set.
944 * To distinguish between a normal closure and an error, use
945 * br_ssl_engine_last_error().
947 * Generally speaking, BR_SSL_SENDREC and BR_SSL_SENDAPP are mutually
948 * exclusive: the input buffer, at any point, either accumulates
949 * plaintext data, or contains an assembled record that is being sent.
950 * Similarly, BR_SSL_RECVREC and BR_SSL_RECVAPP are mutually exclusive.
951 * This may change in a future library version.
954 #define BR_SSL_CLOSED 0x0001
955 #define BR_SSL_SENDREC 0x0002
956 #define BR_SSL_RECVREC 0x0004
957 #define BR_SSL_SENDAPP 0x0008
958 #define BR_SSL_RECVAPP 0x0010
961 * Get the current engine state.
963 unsigned br_ssl_engine_current_state(const br_ssl_engine_context
*cc
);
966 * Get the engine error indicator. This is BR_ERR_OK (0) if no error was
967 * encountered since the last call to br_ssl_client_reset() or
968 * br_ssl_server_reset(). Only these calls clear the error indicator.
971 br_ssl_engine_last_error(const br_ssl_engine_context
*cc
)
977 * There are four I/O operations, each identified by a symbolic name:
979 * sendapp inject application data in the engine
980 * recvapp retrieving application data from the engine
981 * sendrec sending records on the transport medium
982 * recvrec receiving records from the transport medium
984 * Terminology works thus: in a layered model where the SSL engine sits
985 * between the application and the network, "send" designates operations
986 * where bytes flow from application to network, and "recv" for the
987 * reverse operation. Application data (the plaintext that is to be
988 * conveyed through SSL) is "app", while encrypted records are "rec".
989 * Note that from the SSL engine point of view, "sendapp" and "recvrec"
990 * designate bytes that enter the engine ("inject" operation), while
991 * "recvapp" and "sendrec" designate bytes that exit the engine
992 * ("extract" operation).
994 * For the operation 'xxx', two functions are defined:
996 * br_ssl_engine_xxx_buf
997 * Returns a pointer and length to the buffer to use for that
998 * operation. '*len' is set to the number of bytes that may be read
999 * from the buffer (extract operation) or written to the buffer
1000 * (inject operation). If no byte may be exchanged for that operation
1001 * at that point, then '*len' is set to zero, and NULL is returned.
1002 * The engine state is unmodified by this call.
1004 * br_ssl_engine_xxx_ack
1005 * Informs the engine that 'len' bytes have been read from the buffer
1006 * (extract operation) or written to the buffer (inject operation).
1007 * The 'len' value MUST NOT be zero. The 'len' value MUST NOT exceed
1008 * that which was obtained from a preceeding br_ssl_engine_xxx_buf()
1012 unsigned char *br_ssl_engine_sendapp_buf(
1013 const br_ssl_engine_context
*cc
, size_t *len
);
1014 void br_ssl_engine_sendapp_ack(br_ssl_engine_context
*cc
, size_t len
);
1016 unsigned char *br_ssl_engine_recvapp_buf(
1017 const br_ssl_engine_context
*cc
, size_t *len
);
1018 void br_ssl_engine_recvapp_ack(br_ssl_engine_context
*cc
, size_t len
);
1020 unsigned char *br_ssl_engine_sendrec_buf(
1021 const br_ssl_engine_context
*cc
, size_t *len
);
1022 void br_ssl_engine_sendrec_ack(br_ssl_engine_context
*cc
, size_t len
);
1024 unsigned char *br_ssl_engine_recvrec_buf(
1025 const br_ssl_engine_context
*cc
, size_t *len
);
1026 void br_ssl_engine_recvrec_ack(br_ssl_engine_context
*cc
, size_t len
);
1029 * If some application data has been buffered in the engine, then wrap
1030 * it into a record and mark it for sending. If no application data has
1031 * been buffered but the engine would be ready to accept some, AND the
1032 * 'force' parameter is non-zero, then an empty record is assembled and
1033 * marked for sending. In all other cases, this function does nothing.
1035 * Empty records are technically legal, but not all existing SSL/TLS
1036 * implementations support them. Empty records can be useful as a
1037 * transparent "keep-alive" mechanism to maintain some low-level
1040 void br_ssl_engine_flush(br_ssl_engine_context
*cc
, int force
);
1043 * Close the context. If, at that point, the context is open and in
1044 * ready state, then a close_notify alert is assembled and marked for
1045 * sending. Otherwise, no such alert is assembled.
1047 void br_ssl_engine_close(br_ssl_engine_context
*cc
);
1050 * Initiate a renegotiation. If the engine is failed or closed, or if
1051 * the peer is known not to support secure renegotiation (RFC 5746),
1052 * then this function returns 0. Otherwise, this function returns 1 and
1053 * a renegotiation attempt is triggered, unless a handshake is already
1054 * taking place, in which case the call is ignored.
1056 int br_ssl_engine_renegotiate(br_ssl_engine_context
*cc
);
1059 * Context structure for a SSL client.
1063 * The encapsulated engine context.
1065 br_ssl_engine_context eng
;
1068 * Minimum ClientHello length; padding with an extension (RFC
1069 * 7685) is added if necessary to match at least that length.
1070 * Such padding is nominally unnecessary, but it has been used
1071 * to work around some server implementation bugs.
1073 uint16_t min_clienthello_len
;
1078 br_rsa_public irsapub
;
1079 br_rsa_pkcs1_vrfy irsavrfy
;
1080 br_ecdsa_vrfy iecdsa
;
1082 } br_ssl_client_context
;
1085 * Each br_ssl_client_init_xxx() function sets the list of supported
1086 * cipher suites and used implementations, as specified by the profile
1087 * name 'xxx'. Defined profile names are:
1089 * full all supported versions and suites; constant-time implementations
1090 * FIXME: add other profiles
1093 void br_ssl_client_init_full(br_ssl_client_context
*cc
,
1094 br_x509_minimal_context
*xc
,
1095 const br_x509_trust_anchor
*trust_anchors
, size_t trust_anchors_num
);
1098 * Clear the complete contents of a SSL client context, including the
1099 * reference to the configured buffer, implementations, cipher suites
1102 void br_ssl_client_zero(br_ssl_client_context
*cc
);
1105 * Set the RSA public-key operations implementation. This will be used
1106 * to encrypt the pre-master secret with the server's RSA public key
1107 * (RSA-encryption cipher suites only).
1110 br_ssl_client_set_rsapub(br_ssl_client_context
*cc
, br_rsa_public irsapub
)
1112 cc
->irsapub
= irsapub
;
1116 * Set the RSA signature verification implementation. This will be used
1117 * to verify the server's signature on its ServerKeyExchange message
1118 * (ECDHE_RSA cipher suites only).
1121 br_ssl_client_set_rsavrfy(br_ssl_client_context
*cc
, br_rsa_pkcs1_vrfy irsavrfy
)
1123 cc
->irsavrfy
= irsavrfy
;
1127 * Set the ECDSA implementation (signature verification). The ECC core
1128 * implementation must also have been set.
1131 br_ssl_client_set_ecdsa(br_ssl_client_context
*cc
, br_ecdsa_vrfy iecdsa
)
1133 cc
->iecdsa
= iecdsa
;
1137 * Set the minimum ClientHello length (RFC 7685 padding).
1140 br_ssl_client_set_min_clienthello_len(br_ssl_client_context
*cc
, uint16_t len
)
1142 cc
->min_clienthello_len
= len
;
1146 * Prepare or reset a client context for connecting with a server of
1147 * name 'server_name'. The 'server_name' parameter is used to fill the
1148 * SNI extension; if the parameter is NULL then no SNI extension will
1151 * If 'resume_session' is non-zero and the context was previously used
1152 * then the session parameters may be reused (depending on whether the
1153 * server previously sent a non-empty session ID, and accepts the session
1156 * On failure, the context is marked as failed, and this function
1157 * returns 0. A possible failure condition is when no initial entropy
1158 * was injected, and none could be obtained from the OS (either OS
1159 * randomness gathering is not supported, or it failed).
1161 int br_ssl_client_reset(br_ssl_client_context
*cc
,
1162 const char *server_name
, int resume_session
);
1165 * Forget any session in the context. This means that the next handshake
1166 * that uses this context will necessarily be a full handshake (this
1167 * applies both to new connections and to renegotiations).
1170 br_ssl_client_forget_session(br_ssl_client_context
*cc
)
1172 cc
->eng
.session
.session_id_len
= 0;
1176 * Type for a "translated cipher suite", as an array of 16-bit integers:
1177 * first element is the cipher suite identifier (as used on the wire),
1178 * and the second element is the concatenation of four 4-bit elements which
1179 * characterise the cipher suite contents. In most to least significant
1180 * order, these 4-bit elements are:
1182 * Bits 12 to 15: key exchange + server key type
1183 * 0 RSA RSA key exchange, key is RSA (encryption)
1184 * 1 ECDHE-RSA ECDHE key exchange, key is RSA (signature)
1185 * 2 ECDHE-ECDSA ECDHE key exchange, key is EC (signature)
1186 * 3 ECDH-RSA Key is EC (key exchange), cert is signed with RSA
1187 * 4 ECDH-ECDSA Key is EC (key exchange), cert is signed with ECDSA
1189 * Bits 8 to 11: symmetric encryption algorithm
1195 * 5 ChaCha20/Poly1305
1197 * Bits 4 to 7: MAC algorithm
1198 * 0 AEAD No dedicated MAC because encryption is AEAD
1199 * 2 HMAC/SHA-1 Value matches br_sha1_ID
1200 * 4 HMAC/SHA-256 Value matches br_sha256_ID
1201 * 5 HMAC/SHA-384 Value matches br_sha384_ID
1203 * Bits 0 to 3: hash function for PRF when used with TLS-1.2
1204 * 4 SHA-256 Value matches br_sha256_ID
1205 * 5 SHA-384 Value matches br_sha384_ID
1207 typedef uint16_t br_suite_translated
[2];
1209 #define BR_SSLKEYX_RSA 0
1210 #define BR_SSLKEYX_ECDHE_RSA 1
1211 #define BR_SSLKEYX_ECDHE_ECDSA 2
1212 #define BR_SSLKEYX_ECDH_RSA 3
1213 #define BR_SSLKEYX_ECDH_ECDSA 4
1215 #define BR_SSLENC_3DES_CBC 0
1216 #define BR_SSLENC_AES128_CBC 1
1217 #define BR_SSLENC_AES256_CBC 2
1218 #define BR_SSLENC_AES128_GCM 3
1219 #define BR_SSLENC_AES256_GCM 4
1220 #define BR_SSLENC_CHACHA20 5
1222 #define BR_SSLMAC_AEAD 0
1223 #define BR_SSLMAC_SHA1 br_sha1_ID
1224 #define BR_SSLMAC_SHA256 br_sha256_ID
1225 #define BR_SSLMAC_SHA384 br_sha384_ID
1227 #define BR_SSLPRF_SHA256 br_sha256_ID
1228 #define BR_SSLPRF_SHA384 br_sha384_ID
1231 * Pre-declaration for the SSL server context.
1233 typedef struct br_ssl_server_context_ br_ssl_server_context
;
1236 * Type for the server policy choices, taken after analysis of the client
1239 * cipher_suite Cipher suite to use.
1241 * hash_id Signature hash function identifier (hash function
1242 * to use for signing the ServerKeyExchange, when the
1243 * suite uses ECDHE).
1245 * chain The certificate chain to send (number of certificates
1246 * chain_len is in chain_length). The certificates are send "as is"
1247 * and shall be in standard SSL/TLS order (i.e. end-entity
1248 * first, each subsequent certificate signs the previous).
1251 uint16_t cipher_suite
;
1253 const br_x509_certificate
*chain
;
1255 } br_ssl_server_choices
;
1258 * Type for the certificate and private key handler on the server: an
1259 * object with the following methods:
1261 * choose Select the parameters for this connection (cipher suite,
1262 * certificate chain...). The selection is written into the
1263 * '*choices' structure. Returned value is 1 on success, or
1264 * 0 on error (an error here means that the handshake will
1265 * fail, and a handshake_failure alert will be sent to the
1268 * do_keyx Perform the server-side key exchange operation. Returned
1269 * value is 1 on success, 0 on error (see below). This is
1270 * called only when the selected cipher suite calls for a
1271 * RSA or ECDH key exchange involving the server key.
1273 * do_sign Perform the server-side signature operation. Returned
1274 * value is the signature length, or 0 on error (see below).
1275 * This is called only when the selected cipher suite calls
1276 * for an ECDHE key exchange, signed by the server with its key.
1279 * The do_keyx() method shall apply the following semantics:
1281 * -- For RSA key exchange, it shall decrypt the incoming data along
1282 * the rules of PKCS#1 v1.5. The method must verify the proper padding
1283 * and also that the decrypted message length is exactly 48 bytes.
1284 * IMPORTANT: these operations MUST be constant-time (or adequatly blinded).
1285 * The decrypted message is written in the first 48 bytes of data[]. The
1286 * caller makes sure that the data[] buffer is large enough, and that 'len'
1287 * is at least 59 bytes.
1289 * -- For ECDH key exchange, the provided data is an EC point (uncompressed
1290 * format); the method shall multiply that point with the server private
1291 * key, and write the X coordinate of the resulting point in the data[]
1292 * buffer, starting at offset 1 (so if the method produces a compressed or
1293 * uncompressed point, form offset 0, then everything is fine).
1295 * In both cases, returned value is 1 on success, 0 on error.
1298 * The do_sign() method shall compute the signature on the hash value
1299 * provided in the data[] buffer. The 'hv_len' value contains the hash
1300 * value length, while the 'len' parameter is the total size of the
1301 * buffer. The method must verify that the signature length is no more
1302 * than 'len' bytes, and report an error otherwise.
1304 * The hash identifier is either 0 for the MD5+SHA-1 method in TLS-1.0 and
1305 * 1.1, or a non-zero hash function identifier in TLS-1.2 and later. In
1306 * the MD5+SHA-1 method, the hash value has length 36 bytes and there is
1307 * no hash function identifying header to add in the padding.
1309 * Returned value is the signature length (in bytes). On error, this method
1312 typedef struct br_ssl_server_policy_class_ br_ssl_server_policy_class
;
1313 struct br_ssl_server_policy_class_
{
1314 size_t context_size
;
1315 int (*choose
)(const br_ssl_server_policy_class
**pctx
,
1316 const br_ssl_server_context
*cc
,
1317 br_ssl_server_choices
*choices
);
1318 uint32_t (*do_keyx
)(const br_ssl_server_policy_class
**pctx
,
1319 unsigned char *data
, size_t len
);
1320 size_t (*do_sign
)(const br_ssl_server_policy_class
**pctx
,
1321 int hash_id
, size_t hv_len
, unsigned char *data
, size_t len
);
1325 * A single-chain RSA policy handler, that always uses a single chain and
1326 * a RSA key. It may be restricted to do only signatures or only key
1330 const br_ssl_server_policy_class
*vtable
;
1331 const br_x509_certificate
*chain
;
1333 const br_rsa_private_key
*sk
;
1334 unsigned allowed_usages
;
1335 br_rsa_private irsacore
;
1336 br_rsa_pkcs1_sign irsasign
;
1337 } br_ssl_server_policy_rsa_context
;
1340 * A single-chain EC policy handler, that always uses a single chain and
1341 * an EC key. It may be restricted to do only signatures or only key
1345 const br_ssl_server_policy_class
*vtable
;
1346 const br_x509_certificate
*chain
;
1348 const br_ec_private_key
*sk
;
1349 unsigned allowed_usages
;
1350 unsigned cert_issuer_key_type
;
1351 const br_multihash_context
*mhash
;
1352 const br_ec_impl
*iec
;
1353 br_ecdsa_sign iecdsa
;
1354 } br_ssl_server_policy_ec_context
;
1357 * Class type for a session parameter cache.
1359 * save Record session parameters. The session ID has been randomly
1360 * generated, and the session ID length is always 32 bytes.
1361 * The method shall copy the provided information (the structure
1364 * load Find session parameters by ID. The session ID is in the relevant
1365 * field in the '*params' structure, and has always length exactly
1366 * 32 bytes. The method shall fill in the other field with the
1367 * session data, if found. Returned value is 1 when the session was
1368 * found, 0 otherwise.
1370 * Note that the requesting server context is provided. Implementations
1371 * may used some of the resources of that context, e.g. random number
1372 * generator or implementations of some cryptographic algorithms.
1374 typedef struct br_ssl_session_cache_class_ br_ssl_session_cache_class
;
1375 struct br_ssl_session_cache_class_
{
1376 size_t context_size
;
1377 void (*save
)(const br_ssl_session_cache_class
**ctx
,
1378 br_ssl_server_context
*server_ctx
,
1379 const br_ssl_session_parameters
*params
);
1380 int (*load
)(const br_ssl_session_cache_class
**ctx
,
1381 br_ssl_server_context
*server_ctx
,
1382 br_ssl_session_parameters
*params
);
1386 * Context for a very basic cache system that uses a linked list, managed
1387 * with an LRU algorithm (when the cache is full and a new set of parameters
1388 * must be saved, the least recently used entry is evicted). The storage
1389 * buffer is externally provided. Internally, an index tree is used to
1390 * speed up operations.
1393 const br_ssl_session_cache_class
*vtable
;
1394 unsigned char *store
;
1395 size_t store_len
, store_ptr
;
1396 unsigned char index_key
[32];
1397 const br_hash_class
*hash
;
1399 uint32_t head
, tail
, root
;
1400 } br_ssl_session_cache_lru
;
1403 * Initialise a LRU session cache with the provided storage space.
1405 void br_ssl_session_cache_lru_init(br_ssl_session_cache_lru
*cc
,
1406 unsigned char *store
, size_t store_len
);
1409 * Context structure for a SSL server.
1411 struct br_ssl_server_context_
{
1413 * The encapsulated engine context.
1415 br_ssl_engine_context eng
;
1418 * Maximum version from the client.
1420 uint16_t client_max_version
;
1425 const br_ssl_session_cache_class
**cache_vtable
;
1428 * Translated cipher suites supported by the client. The list
1429 * is trimmed to include only the cipher suites that the
1430 * server also supports; they are in the same order as in the
1433 br_suite_translated client_suites
[BR_MAX_CIPHER_SUITES
];
1434 unsigned char client_suites_num
;
1437 * Hash functions supported by the client, with ECDSA and RSA
1438 * (bit mask). For hash function with id 'x', set bit index is
1439 * x for RSA, x+8 for ECDSA.
1444 * Curves supported by the client (bit mask, for named curves).
1449 * Context for chain handler.
1451 const br_ssl_server_policy_class
**policy_vtable
;
1452 const br_x509_certificate
*chain
;
1454 const unsigned char *cert_cur
;
1456 unsigned char sign_hash_id
;
1459 * For the core handlers, thus avoiding (in most cases) the
1460 * need for an externally provided policy context.
1463 const br_ssl_server_policy_class
*vtable
;
1464 br_ssl_server_policy_rsa_context single_rsa
;
1465 br_ssl_server_policy_ec_context single_ec
;
1469 * Buffer for the ECDHE private key.
1471 unsigned char ecdhe_key
[70];
1472 size_t ecdhe_key_len
;
1475 * Server-specific implementations.
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 * If this flag is set, then renegotiations are rejected unconditionally:
1487 * they won't be honoured if asked for programmatically, and requests from
1488 * the peer are rejected.
1490 #define BR_OPT_NO_RENEGOTIATION ((uint32_t)1 << 1)
1493 * Each br_ssl_server_init_xxx() function sets the list of supported
1494 * cipher suites and used implementations, as specified by the profile
1495 * name 'xxx'. Defined profile names are:
1497 * full_rsa all supported algorithm, server key type is RSA
1498 * full_ec all supported algorithm, server key type is EC
1499 * FIXME: add other profiles
1501 * Naming scheme for "minimal" profiles: min123
1503 * -- character 1: key exchange
1509 * -- character 2: version / PRF
1510 * 0 = TLS 1.0 / 1.1 with MD5+SHA-1
1511 * 2 = TLS 1.2 with SHA-256
1512 * 3 = TLS 1.2 with SHA-384
1513 * -- character 3: encryption
1519 void br_ssl_server_init_full_rsa(br_ssl_server_context
*cc
,
1520 const br_x509_certificate
*chain
, size_t chain_len
,
1521 const br_rsa_private_key
*sk
);
1523 void br_ssl_server_init_full_ec(br_ssl_server_context
*cc
,
1524 const br_x509_certificate
*chain
, size_t chain_len
,
1525 unsigned cert_issuer_key_type
, const br_ec_private_key
*sk
);
1527 void br_ssl_server_init_minr2g(br_ssl_server_context
*cc
,
1528 const br_x509_certificate
*chain
, size_t chain_len
,
1529 const br_rsa_private_key
*sk
);
1530 void br_ssl_server_init_mine2g(br_ssl_server_context
*cc
,
1531 const br_x509_certificate
*chain
, size_t chain_len
,
1532 const br_rsa_private_key
*sk
);
1533 void br_ssl_server_init_minf2g(br_ssl_server_context
*cc
,
1534 const br_x509_certificate
*chain
, size_t chain_len
,
1535 const br_ec_private_key
*sk
);
1536 void br_ssl_server_init_minu2g(br_ssl_server_context
*cc
,
1537 const br_x509_certificate
*chain
, size_t chain_len
,
1538 const br_ec_private_key
*sk
);
1539 void br_ssl_server_init_minv2g(br_ssl_server_context
*cc
,
1540 const br_x509_certificate
*chain
, size_t chain_len
,
1541 const br_ec_private_key
*sk
);
1544 * Get the supported client suites. The returned array is ordered by
1545 * client or server preferences, depending on the relevant flag.
1547 static inline const br_suite_translated
*
1548 br_ssl_server_get_client_suites(const br_ssl_server_context
*cc
, size_t *num
)
1550 *num
= cc
->client_suites_num
;
1551 return cc
->client_suites
;
1555 * Get the hash functions supported by the client. This is a field of
1556 * bits: for hash function of ID x, bit x is set if the hash function
1557 * is supported in RSA signatures, 8+x if it is supported with ECDSA.
1559 static inline uint16_t
1560 br_ssl_server_get_client_hashes(const br_ssl_server_context
*cc
)
1566 * Get the elliptic curves supported by the client. This is a bit field
1567 * (bit x is set if curve of ID x is supported).
1569 static inline uint32_t
1570 br_ssl_server_get_client_curves(const br_ssl_server_context
*cc
)
1576 * Clear the complete contents of a SSL server context, including the
1577 * reference to the configured buffer, implementations, cipher suites
1580 void br_ssl_server_zero(br_ssl_server_context
*cc
);
1583 * Set an externally provided policy context.
1586 br_ssl_server_set_policy(br_ssl_server_context
*cc
,
1587 const br_ssl_server_policy_class
**pctx
)
1589 cc
->policy_vtable
= pctx
;
1593 * Set the server certificate chain and key (single RSA case).
1594 * The 'allowed_usages' is a combination of usages, namely
1595 * BR_KEYTYPE_KEYX and/or BR_KEYTYPE_SIGN.
1597 void br_ssl_server_set_single_rsa(br_ssl_server_context
*cc
,
1598 const br_x509_certificate
*chain
, size_t chain_length
,
1599 const br_rsa_private_key
*sk
, unsigned allowed_usages
,
1600 br_rsa_private irsacore
, br_rsa_pkcs1_sign irsasign
);
1603 * Set the server certificate chain and key (single EC case).
1604 * The 'allowed_usages' is a combination of usages, namely
1605 * BR_KEYTYPE_KEYX and/or BR_KEYTYPE_SIGN.
1607 void br_ssl_server_set_single_ec(br_ssl_server_context
*cc
,
1608 const br_x509_certificate
*chain
, size_t chain_length
,
1609 const br_ec_private_key
*sk
, unsigned allowed_usages
,
1610 unsigned cert_issuer_key_type
,
1611 const br_ec_impl
*iec
, br_ecdsa_sign iecdsa
);
1614 * Configure the server context to use the provided cache for session
1618 br_ssl_server_set_cache(br_ssl_server_context
*cc
,
1619 const br_ssl_session_cache_class
**vtable
)
1621 cc
->cache_vtable
= vtable
;
1625 * Prepare or reset a server context for handling an incoming client.
1627 int br_ssl_server_reset(br_ssl_server_context
*cc
);
1629 /* ===================================================================== */
1632 * Context for the simplified I/O context. The transport medium is accessed
1633 * through the low_read() and low_write() callback functions, each with
1634 * its own opaque context pointer.
1636 * low_read() read some bytes, at most 'len' bytes, into data[]. The
1637 * returned value is the number of read bytes, or -1 on error.
1638 * The 'len' parameter is guaranteed never to exceed 20000,
1639 * so the length always fits in an 'int' on all platforms.
1641 * low_write() write up to 'len' bytes, to be read from data[]. The
1642 * returned value is the number of written bytes, or -1 on
1643 * error. The 'len' parameter is guaranteed never to exceed
1644 * 20000, so the length always fits in an 'int' on all
1647 * A socket closure (if the transport medium is a socket) should be reported
1648 * as an error (-1). The callbacks shall endeavour to block until at least
1649 * one byte can be read or written; a callback returning 0 at times is
1650 * acceptable, but this normally leads to the callback being immediately
1651 * called again, so the callback should at least always try to block for
1652 * some time if no I/O can take place.
1654 * The SSL engine naturally applies some buffering, so the callbacks need
1655 * not apply buffers of their own.
1658 br_ssl_engine_context
*engine
;
1659 int (*low_read
)(void *read_context
,
1660 unsigned char *data
, size_t len
);
1662 int (*low_write
)(void *write_context
,
1663 const unsigned char *data
, size_t len
);
1664 void *write_context
;
1668 * Initialise a simplified I/O context over the provided engine and
1671 void br_sslio_init(br_sslio_context
*ctx
,
1672 br_ssl_engine_context
*engine
,
1673 int (*low_read
)(void *read_context
,
1674 unsigned char *data
, size_t len
),
1676 int (*low_write
)(void *write_context
,
1677 const unsigned char *data
, size_t len
),
1678 void *write_context
);
1681 * Read some application data from a SSL connection. This call returns
1682 * only when at least one byte has been obtained. Returned value is
1683 * the number of bytes read, or -1 on error. The number of bytes
1684 * always fits on an 'int' (data from a single SSL/TLS record is
1687 * On error or SSL closure, this function returns -1. The caller should
1688 * inspect the error status on the SSL engine to distinguish between
1689 * normal closure and error.
1691 int br_sslio_read(br_sslio_context
*cc
, void *dst
, size_t len
);
1694 * Read some application data from a SSL connection. This call returns
1695 * only when ALL requested bytes have been read. Returned value is 0
1696 * on success, -1 on error. A normal SSL closure before that many bytes
1697 * are obtained is reported as an error by this function.
1699 int br_sslio_read_all(br_sslio_context
*cc
, void *dst
, size_t len
);
1702 * Write some application data onto a SSL connection. This call returns
1703 * only when at least one byte had been written onto the connection (but
1704 * not necessarily flushed). Returned value is the number of written
1705 * bytes, or -1 on error (error conditions include a closed connection).
1706 * It is guaranteed that the number of bytes written by such a call will
1707 * fit in an 'int' on all architectures.
1709 * Note that some written bytes may be buffered; use br_sslio_flush()
1710 * to make sure that the data is sent to the transport stream.
1712 int br_sslio_write(br_sslio_context
*cc
, const void *src
, size_t len
);
1715 * Write some application data onto a SSL connection. This call returns
1716 * only when ALL the bytes have been written onto the connection (but
1717 * not necessarily flushed). Returned value is 0 on success, -1 on error.
1719 * Note that some written bytes may be buffered; use br_sslio_flush()
1720 * to make sure that the data is sent to the transport stream.
1722 int br_sslio_write_all(br_sslio_context
*cc
, const void *src
, size_t len
);
1725 * Make sure that any buffered application data in the provided context
1726 * get packed up and sent unto the low_write() callback method. If that
1727 * callback method represents a buffered system, it is up to the caller
1728 * to then "flush" that system too.
1730 * Returned value is 0 on success, -1 on error.
1732 int br_sslio_flush(br_sslio_context
*cc
);
1735 * Perform a SSL close. This implies sending a close_notify, and reading
1736 * the response from the server. Returned value is 0 on success, -1 on
1739 int br_sslio_close(br_sslio_context
*cc
);
1741 /* ===================================================================== */
1744 * Symbolic constants for cipher suites.
1748 #define BR_TLS_NULL_WITH_NULL_NULL 0x0000
1749 #define BR_TLS_RSA_WITH_NULL_MD5 0x0001
1750 #define BR_TLS_RSA_WITH_NULL_SHA 0x0002
1751 #define BR_TLS_RSA_WITH_NULL_SHA256 0x003B
1752 #define BR_TLS_RSA_WITH_RC4_128_MD5 0x0004
1753 #define BR_TLS_RSA_WITH_RC4_128_SHA 0x0005
1754 #define BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA 0x000A
1755 #define BR_TLS_RSA_WITH_AES_128_CBC_SHA 0x002F
1756 #define BR_TLS_RSA_WITH_AES_256_CBC_SHA 0x0035
1757 #define BR_TLS_RSA_WITH_AES_128_CBC_SHA256 0x003C
1758 #define BR_TLS_RSA_WITH_AES_256_CBC_SHA256 0x003D
1759 #define BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 0x000D
1760 #define BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 0x0010
1761 #define BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 0x0013
1762 #define BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 0x0016
1763 #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA 0x0030
1764 #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA 0x0031
1765 #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA 0x0032
1766 #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA 0x0033
1767 #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA 0x0036
1768 #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA 0x0037
1769 #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA 0x0038
1770 #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x0039
1771 #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256 0x003E
1772 #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256 0x003F
1773 #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 0x0040
1774 #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 0x0067
1775 #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256 0x0068
1776 #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256 0x0069
1777 #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 0x006A
1778 #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 0x006B
1779 #define BR_TLS_DH_anon_WITH_RC4_128_MD5 0x0018
1780 #define BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 0x001B
1781 #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA 0x0034
1782 #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA 0x003A
1783 #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256 0x006C
1784 #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256 0x006D
1787 #define BR_TLS_ECDH_ECDSA_WITH_NULL_SHA 0xC001
1788 #define BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0xC002
1789 #define BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC003
1790 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0xC004
1791 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0xC005
1792 #define BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA 0xC006
1793 #define BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0xC007
1794 #define BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC008
1795 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0xC009
1796 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0xC00A
1797 #define BR_TLS_ECDH_RSA_WITH_NULL_SHA 0xC00B
1798 #define BR_TLS_ECDH_RSA_WITH_RC4_128_SHA 0xC00C
1799 #define BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0xC00D
1800 #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0xC00E
1801 #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0xC00F
1802 #define BR_TLS_ECDHE_RSA_WITH_NULL_SHA 0xC010
1803 #define BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA 0xC011
1804 #define BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0xC012
1805 #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0xC013
1806 #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC014
1807 #define BR_TLS_ECDH_anon_WITH_NULL_SHA 0xC015
1808 #define BR_TLS_ECDH_anon_WITH_RC4_128_SHA 0xC016
1809 #define BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 0xC017
1810 #define BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA 0xC018
1811 #define BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA 0xC019
1814 #define BR_TLS_RSA_WITH_AES_128_GCM_SHA256 0x009C
1815 #define BR_TLS_RSA_WITH_AES_256_GCM_SHA384 0x009D
1816 #define BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 0x009E
1817 #define BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 0x009F
1818 #define BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256 0x00A0
1819 #define BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384 0x00A1
1820 #define BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 0x00A2
1821 #define BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 0x00A3
1822 #define BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256 0x00A4
1823 #define BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384 0x00A5
1824 #define BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256 0x00A6
1825 #define BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384 0x00A7
1828 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023
1829 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024
1830 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC025
1831 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0xC026
1832 #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0xC027
1833 #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC028
1834 #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0xC029
1835 #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0xC02A
1836 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B
1837 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C
1838 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 0xC02D
1839 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 0xC02E
1840 #define BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC02F
1841 #define BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xC030
1842 #define BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 0xC031
1843 #define BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 0xC032
1846 #define BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8
1847 #define BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9
1848 #define BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCAA
1849 #define BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAB
1850 #define BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAC
1851 #define BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAD
1852 #define BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAE
1855 * Symbolic constants for alerts.
1857 #define BR_ALERT_CLOSE_NOTIFY 0
1858 #define BR_ALERT_UNEXPECTED_MESSAGE 10
1859 #define BR_ALERT_BAD_RECORD_MAC 20
1860 #define BR_ALERT_RECORD_OVERFLOW 22
1861 #define BR_ALERT_DECOMPRESSION_FAILURE 30
1862 #define BR_ALERT_HANDSHAKE_FAILURE 40
1863 #define BR_ALERT_BAD_CERTIFICATE 42
1864 #define BR_ALERT_UNSUPPORTED_CERTIFICATE 43
1865 #define BR_ALERT_CERTIFICATE_REVOKED 44
1866 #define BR_ALERT_CERTIFICATE_EXPIRED 45
1867 #define BR_ALERT_CERTIFICATE_UNKNOWN 46
1868 #define BR_ALERT_ILLEGAL_PARAMETER 47
1869 #define BR_ALERT_UNKNOWN_CA 48
1870 #define BR_ALERT_ACCESS_DENIED 49
1871 #define BR_ALERT_DECODE_ERROR 50
1872 #define BR_ALERT_DECRYPT_ERROR 51
1873 #define BR_ALERT_PROTOCOL_VERSION 70
1874 #define BR_ALERT_INSUFFICIENT_SECURITY 71
1875 #define BR_ALERT_INTERNAL_ERROR 80
1876 #define BR_ALERT_USER_CANCELED 90
1877 #define BR_ALERT_NO_RENEGOTIATION 100
1878 #define BR_ALERT_UNSUPPORTED_EXTENSION 110