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];
547 br_ssl_session_parameters session
;
550 * ECDHE elements: curve and point from the peer. The server also
551 * uses that buffer for the point to send to the client.
553 unsigned char ecdhe_curve
;
554 unsigned char ecdhe_point
[133];
555 unsigned char ecdhe_point_len
;
558 * Secure renegotiation (RFC 5746): 'reneg' can be:
559 * 0 first handshake (server support is not known)
560 * 1 server does not support secure renegotiation
561 * 2 server supports secure renegotiation
563 * The saved_finished buffer contains the client and the
564 * server "Finished" values from the last handshake, in
565 * that order (12 bytes each).
568 unsigned char saved_finished
[24];
576 * Context variables for the handshake processor.
577 * The 'pad' must be large enough to accommodate an
578 * RSA-encrypted pre-master secret, or a RSA signature on
579 * key exchange parameters; since we want to support up to
580 * RSA-4096, this means at least 512 bytes.
581 * (Other pad usages require its length to be at least 256.)
586 const unsigned char *ip
;
588 uint32_t dp_stack
[32];
589 uint32_t rp_stack
[32];
590 unsigned char pad
[512];
591 unsigned char *hbuf_in
, *hbuf_out
, *saved_hbuf_out
;
592 size_t hlen_in
, hlen_out
;
593 void (*hsrun
)(void *ctx
);
596 * The 'action' value communicates OOB information between the
597 * engine and the handshake processor.
600 * 0 invocation triggered by I/O
601 * 1 invocation triggered by explicit close
602 * 2 invocation triggered by explicit renegotiation
604 unsigned char action
;
607 * State for alert messages. Value is either 0, or the value of
608 * the alert level byte (level is either 1 for warning, or 2 for
609 * fatal; we convert all other values to 'fatal').
614 * Closure flags. This flag is set when a close_notify has been
615 * received from the peer.
617 unsigned char close_received
;
620 * Multi-hasher for the handshake messages. The handshake handler
621 * is responsible for resetting it when appropriate.
623 br_multihash_context mhash
;
626 * Pointer to the X.509 engine. The engine is supposed to be
627 * already initialized. It is used to validate the peer's
630 const br_x509_class
**x509ctx
;
633 * Pointers to implementations; left to NULL for unsupported
634 * functions. For the raw hash functions, implementations are
635 * referenced from the multihasher (mhash field).
637 br_tls_prf_impl prf10
;
638 br_tls_prf_impl prf_sha256
;
639 br_tls_prf_impl prf_sha384
;
640 const br_block_cbcenc_class
*iaes_cbcenc
;
641 const br_block_cbcdec_class
*iaes_cbcdec
;
642 const br_block_ctr_class
*iaes_ctr
;
643 const br_block_cbcenc_class
*ides_cbcenc
;
644 const br_block_cbcdec_class
*ides_cbcdec
;
646 const br_sslrec_in_cbc_class
*icbc_in
;
647 const br_sslrec_out_cbc_class
*icbc_out
;
648 const br_sslrec_in_gcm_class
*igcm_in
;
649 const br_sslrec_out_gcm_class
*igcm_out
;
650 const br_ec_impl
*iec
;
652 } br_ssl_engine_context
;
655 * Get currently defined engine behavioural flags.
657 static inline uint32_t
658 br_ssl_engine_get_flags(br_ssl_engine_context
*cc
)
664 * Set all engine flags. Flags which are not in the 'flags' argument
668 br_ssl_engine_set_all_flags(br_ssl_engine_context
*cc
, uint32_t flags
)
674 * Add some engine flags. The provided flags are set in the engine context,
675 * but other flags are untouched.
678 br_ssl_engine_add_flags(br_ssl_engine_context
*cc
, uint32_t flags
)
684 * Remove some engine flags. The provided flags are cleared from the
685 * engine context, but other flags are untouched.
688 br_ssl_engine_remove_flags(br_ssl_engine_context
*cc
, uint32_t flags
)
694 * Set the minimum and maximum supported protocol versions.
697 br_ssl_engine_set_versions(br_ssl_engine_context
*cc
,
698 unsigned version_min
, unsigned version_max
)
700 cc
->version_min
= version_min
;
701 cc
->version_max
= version_max
;
705 * Set the list of cipher suites advertised by this context. The provided
706 * array is copied into the context. It is the caller responsibility
707 * to ensure that all provided suites will be supported by the context.
709 void br_ssl_engine_set_suites(br_ssl_engine_context
*cc
,
710 const uint16_t *suites
, size_t suites_num
);
713 * Set the X.509 engine. The context should be already initialized and
714 * ready to process a new chain.
717 br_ssl_engine_set_x509(br_ssl_engine_context
*cc
, const br_x509_class
**x509ctx
)
719 cc
->x509ctx
= x509ctx
;
723 * Set a hash function implementation (by ID).
726 br_ssl_engine_set_hash(br_ssl_engine_context
*ctx
,
727 int id
, const br_hash_class
*impl
)
729 br_multihash_setimpl(&ctx
->mhash
, id
, impl
);
733 * Get a hash function implementation (by ID).
735 static inline const br_hash_class
*
736 br_ssl_engine_get_hash(br_ssl_engine_context
*ctx
, int id
)
738 return br_multihash_getimpl(&ctx
->mhash
, id
);
742 * Set the PRF implementation (for TLS 1.0 and 1.1).
745 br_ssl_engine_set_prf10(br_ssl_engine_context
*cc
, br_tls_prf_impl impl
)
751 * Set the PRF implementation (for TLS 1.2, with SHA-256).
754 br_ssl_engine_set_prf_sha256(br_ssl_engine_context
*cc
, br_tls_prf_impl impl
)
756 cc
->prf_sha256
= impl
;
760 * Set the PRF implementation (for TLS 1.2, with SHA-384).
763 br_ssl_engine_set_prf_sha384(br_ssl_engine_context
*cc
, br_tls_prf_impl impl
)
765 cc
->prf_sha384
= impl
;
769 * Set the AES/CBC implementations.
772 br_ssl_engine_set_aes_cbc(br_ssl_engine_context
*cc
,
773 const br_block_cbcenc_class
*impl_enc
,
774 const br_block_cbcdec_class
*impl_dec
)
776 cc
->iaes_cbcenc
= impl_enc
;
777 cc
->iaes_cbcdec
= impl_dec
;
781 * Set the AES/CTR implementation.
784 br_ssl_engine_set_aes_ctr(br_ssl_engine_context
*cc
,
785 const br_block_ctr_class
*impl
)
791 * Set the 3DES/CBC implementations.
794 br_ssl_engine_set_des_cbc(br_ssl_engine_context
*cc
,
795 const br_block_cbcenc_class
*impl_enc
,
796 const br_block_cbcdec_class
*impl_dec
)
798 cc
->ides_cbcenc
= impl_enc
;
799 cc
->ides_cbcdec
= impl_dec
;
803 * Set the GHASH implementation (for GCM).
806 br_ssl_engine_set_ghash(br_ssl_engine_context
*cc
, br_ghash impl
)
812 * Set the CBC+HMAC record processor implementations.
815 br_ssl_engine_set_cbc(br_ssl_engine_context
*cc
,
816 const br_sslrec_in_cbc_class
*impl_in
,
817 const br_sslrec_out_cbc_class
*impl_out
)
819 cc
->icbc_in
= impl_in
;
820 cc
->icbc_out
= impl_out
;
824 * Set the GCM record processor implementations.
827 br_ssl_engine_set_gcm(br_ssl_engine_context
*cc
,
828 const br_sslrec_in_gcm_class
*impl_in
,
829 const br_sslrec_out_gcm_class
*impl_out
)
831 cc
->igcm_in
= impl_in
;
832 cc
->igcm_out
= impl_out
;
836 * Set the ECC core operations implementation. The 'iec' parameter
837 * points to the core EC code used for both ECDHE and ECDSA.
840 br_ssl_engine_set_ec(br_ssl_engine_context
*cc
, const br_ec_impl
*iec
)
846 * Set the I/O buffer for a SSL engine. Once this call has been made,
847 * br_ssl_client_reset() or br_ssl_server_reset() must be called before
850 * If 'bidi' is 1, then the buffer will be internally split to support
851 * concurrent input and output; otherwise, the caller will be responsible
852 * for reading all buffered incoming data before writing. The latter
853 * case makes support of HTTPS pipelining difficult, thus bidirectional
854 * buffering is recommended if the RAM can be spared.
856 * The BR_SSL_BUFSIZE_MONO and BR_SSL_BUFSIZE_BIDI macros yield optimal
857 * buffer sizes for the monodirectional and bidirectional cases,
858 * respectively. If using optimal sizes (or larger), then records with
859 * the maximum length supported by the TLS standard will be accepted
862 void br_ssl_engine_set_buffer(br_ssl_engine_context
*cc
,
863 void *iobuf
, size_t iobuf_len
, int bidi
);
866 * Set the I/O buffers for a SSL engine. This call sets two buffers, for
867 * concurrent input and output. The two buffers MUST be disjoint. Once
868 * this call has been made, br_ssl_client_reset() or
869 * br_ssl_server_reset() must be called before using the context.
871 * The BR_SSL_BUFSIZE_INPUT and BR_SSL_BUFSIZE_OUTPUT macros evaluate to
872 * optimal sizes for the input and output buffers, respectively. If
873 * using optimal sizes (or larger), then records with the maximum length
874 * supported by the TLS standard will be accepted and emitted.
876 void br_ssl_engine_set_buffers_bidi(br_ssl_engine_context
*cc
,
877 void *ibuf
, size_t ibuf_len
, void *obuf
, size_t obuf_len
);
880 * Inject some "initial entropy" in the context. This entropy will be added
881 * to what can be obtained from the underlying operating system, if that
884 * This function may be called several times; all injected entropy chunks
885 * are cumulatively mixed.
887 * If entropy gathering from the OS is supported and compiled in, then this
888 * step is optional. Otherwise, it is mandatory to inject randomness, and
889 * the caller MUST take care to push (as one or several successive calls)
890 * enough entropy to achieve cryptographic resistance (at least 80 bits,
891 * preferably 128 or more). The engine will report an error if no entropy
892 * was provided and none can be obtained from the OS.
894 * Take care that this function cannot assess the cryptographic quality of
895 * the provided bytes.
897 * In all generality, "entropy" must here be considered to mean "that
898 * which the attacker cannot predict". If your OS/architecture does not
899 * have a suitable source of randomness, then you can make do with the
900 * combination of a large enough secret value (possibly a copy of an
901 * asymmetric private key that you also store on the system) AND a
902 * non-repeating value (e.g. current time, provided that the local clock
903 * cannot be reset or altered by the attacker).
905 void br_ssl_engine_inject_entropy(br_ssl_engine_context
*cc
,
906 const void *data
, size_t len
);
909 * Get the "server name" in this engine. For clients, this is the name
910 * provided with br_ssl_client_reset(); for servers, this is the name
911 * received from the client as part of the ClientHello message. If there
912 * is no such name (e.g. the client did not send an SNI extension) then
913 * the returned string is empty (returned pointer points to a byte of
916 static inline const char *
917 br_ssl_engine_get_server_name(br_ssl_engine_context
*cc
)
919 return cc
->server_name
;
923 * Get a copy of the session parameters. The session parameters are
924 * filled during the handshake, so this function shall not be called
925 * before completion of the handshake.
928 br_ssl_engine_get_session_parameters(const br_ssl_engine_context
*cc
,
929 br_ssl_session_parameters
*pp
)
931 memcpy(pp
, &cc
->session
, sizeof *pp
);
935 * Set the session parameters to the provided value. This function
936 * is meant to be used in the client, before doing a new handshake;
937 * a session resumption will be attempted with these parameters. In
938 * the server, this function has no effect.
941 br_ssl_engine_set_session_parameters(br_ssl_engine_context
*cc
,
942 const br_ssl_session_parameters
*pp
)
944 memcpy(&cc
->session
, pp
, sizeof *pp
);
948 * An SSL engine (client or server) has, at any time, a state which is
949 * the combination of zero, one or more of these flags:
951 * BR_SSL_CLOSED engine is finished, no more I/O (until next reset)
952 * BR_SSL_SENDREC engine has some bytes to send to the peer
953 * BR_SSL_RECVREC engine expects some bytes from the peer
954 * BR_SSL_SENDAPP engine may receive application data to send (or flush)
955 * BR_SSL_RECVAPP engine has obtained some application data from the peer,
956 * that should be read by the caller
958 * If no flag at all is set (state value is 0), then the engine is not
959 * fully initialized yet.
961 * The BR_SSL_CLOSED flag is exclusive; when it is set, no other flag is set.
962 * To distinguish between a normal closure and an error, use
963 * br_ssl_engine_last_error().
965 * Generally speaking, BR_SSL_SENDREC and BR_SSL_SENDAPP are mutually
966 * exclusive: the input buffer, at any point, either accumulates
967 * plaintext data, or contains an assembled record that is being sent.
968 * Similarly, BR_SSL_RECVREC and BR_SSL_RECVAPP are mutually exclusive.
969 * This may change in a future library version.
972 #define BR_SSL_CLOSED 0x0001
973 #define BR_SSL_SENDREC 0x0002
974 #define BR_SSL_RECVREC 0x0004
975 #define BR_SSL_SENDAPP 0x0008
976 #define BR_SSL_RECVAPP 0x0010
979 * Get the current engine state.
981 unsigned br_ssl_engine_current_state(const br_ssl_engine_context
*cc
);
984 * Get the engine error indicator. This is BR_ERR_OK (0) if no error was
985 * encountered since the last call to br_ssl_client_reset() or
986 * br_ssl_server_reset(). Only these calls clear the error indicator.
989 br_ssl_engine_last_error(const br_ssl_engine_context
*cc
)
995 * There are four I/O operations, each identified by a symbolic name:
997 * sendapp inject application data in the engine
998 * recvapp retrieving application data from the engine
999 * sendrec sending records on the transport medium
1000 * recvrec receiving records from the transport medium
1002 * Terminology works thus: in a layered model where the SSL engine sits
1003 * between the application and the network, "send" designates operations
1004 * where bytes flow from application to network, and "recv" for the
1005 * reverse operation. Application data (the plaintext that is to be
1006 * conveyed through SSL) is "app", while encrypted records are "rec".
1007 * Note that from the SSL engine point of view, "sendapp" and "recvrec"
1008 * designate bytes that enter the engine ("inject" operation), while
1009 * "recvapp" and "sendrec" designate bytes that exit the engine
1010 * ("extract" operation).
1012 * For the operation 'xxx', two functions are defined:
1014 * br_ssl_engine_xxx_buf
1015 * Returns a pointer and length to the buffer to use for that
1016 * operation. '*len' is set to the number of bytes that may be read
1017 * from the buffer (extract operation) or written to the buffer
1018 * (inject operation). If no byte may be exchanged for that operation
1019 * at that point, then '*len' is set to zero, and NULL is returned.
1020 * The engine state is unmodified by this call.
1022 * br_ssl_engine_xxx_ack
1023 * Informs the engine that 'len' bytes have been read from the buffer
1024 * (extract operation) or written to the buffer (inject operation).
1025 * The 'len' value MUST NOT be zero. The 'len' value MUST NOT exceed
1026 * that which was obtained from a preceeding br_ssl_engine_xxx_buf()
1030 unsigned char *br_ssl_engine_sendapp_buf(
1031 const br_ssl_engine_context
*cc
, size_t *len
);
1032 void br_ssl_engine_sendapp_ack(br_ssl_engine_context
*cc
, size_t len
);
1034 unsigned char *br_ssl_engine_recvapp_buf(
1035 const br_ssl_engine_context
*cc
, size_t *len
);
1036 void br_ssl_engine_recvapp_ack(br_ssl_engine_context
*cc
, size_t len
);
1038 unsigned char *br_ssl_engine_sendrec_buf(
1039 const br_ssl_engine_context
*cc
, size_t *len
);
1040 void br_ssl_engine_sendrec_ack(br_ssl_engine_context
*cc
, size_t len
);
1042 unsigned char *br_ssl_engine_recvrec_buf(
1043 const br_ssl_engine_context
*cc
, size_t *len
);
1044 void br_ssl_engine_recvrec_ack(br_ssl_engine_context
*cc
, size_t len
);
1047 * If some application data has been buffered in the engine, then wrap
1048 * it into a record and mark it for sending. If no application data has
1049 * been buffered but the engine would be ready to accept some, AND the
1050 * 'force' parameter is non-zero, then an empty record is assembled and
1051 * marked for sending. In all other cases, this function does nothing.
1053 * Empty records are technically legal, but not all existing SSL/TLS
1054 * implementations support them. Empty records can be useful as a
1055 * transparent "keep-alive" mechanism to maintain some low-level
1058 void br_ssl_engine_flush(br_ssl_engine_context
*cc
, int force
);
1061 * Close the context. If, at that point, the context is open and in
1062 * ready state, then a close_notify alert is assembled and marked for
1063 * sending. Otherwise, no such alert is assembled.
1065 void br_ssl_engine_close(br_ssl_engine_context
*cc
);
1068 * Initiate a renegotiation. If the engine is failed or closed, or if
1069 * the peer is known not to support secure renegotiation (RFC 5746),
1070 * then this function returns 0. Otherwise, this function returns 1 and
1071 * a renegotiation attempt is triggered, unless a handshake is already
1072 * taking place, in which case the call is ignored.
1074 int br_ssl_engine_renegotiate(br_ssl_engine_context
*cc
);
1077 * Context structure for a SSL client.
1081 * The encapsulated engine context.
1083 br_ssl_engine_context eng
;
1086 * Minimum ClientHello length; padding with an extension (RFC
1087 * 7685) is added if necessary to match at least that length.
1088 * Such padding is nominally unnecessary, but it has been used
1089 * to work around some server implementation bugs.
1091 uint16_t min_clienthello_len
;
1096 br_rsa_public irsapub
;
1097 br_rsa_pkcs1_vrfy irsavrfy
;
1098 br_ecdsa_vrfy iecdsa
;
1100 } br_ssl_client_context
;
1103 * Each br_ssl_client_init_xxx() function sets the list of supported
1104 * cipher suites and used implementations, as specified by the profile
1105 * name 'xxx'. Defined profile names are:
1107 * full all supported versions and suites; constant-time implementations
1108 * FIXME: add other profiles
1111 void br_ssl_client_init_full(br_ssl_client_context
*cc
,
1112 br_x509_minimal_context
*xc
,
1113 const br_x509_trust_anchor
*trust_anchors
, size_t trust_anchors_num
);
1116 * Clear the complete contents of a SSL client context, including the
1117 * reference to the configured buffer, implementations, cipher suites
1120 void br_ssl_client_zero(br_ssl_client_context
*cc
);
1123 * Set the RSA public-key operations implementation. This will be used
1124 * to encrypt the pre-master secret with the server's RSA public key
1125 * (RSA-encryption cipher suites only).
1128 br_ssl_client_set_rsapub(br_ssl_client_context
*cc
, br_rsa_public irsapub
)
1130 cc
->irsapub
= irsapub
;
1134 * Set the RSA signature verification implementation. This will be used
1135 * to verify the server's signature on its ServerKeyExchange message
1136 * (ECDHE_RSA cipher suites only).
1139 br_ssl_client_set_rsavrfy(br_ssl_client_context
*cc
, br_rsa_pkcs1_vrfy irsavrfy
)
1141 cc
->irsavrfy
= irsavrfy
;
1145 * Set the ECDSA implementation (signature verification). The ECC core
1146 * implementation must also have been set.
1149 br_ssl_client_set_ecdsa(br_ssl_client_context
*cc
, br_ecdsa_vrfy iecdsa
)
1151 cc
->iecdsa
= iecdsa
;
1155 * Set the minimum ClientHello length (RFC 7685 padding).
1158 br_ssl_client_set_min_clienthello_len(br_ssl_client_context
*cc
, uint16_t len
)
1160 cc
->min_clienthello_len
= len
;
1164 * Prepare or reset a client context for connecting with a server of
1165 * name 'server_name'. The 'server_name' parameter is used to fill the
1166 * SNI extension; if the parameter is NULL then no SNI extension will
1169 * If 'resume_session' is non-zero and the context was previously used
1170 * then the session parameters may be reused (depending on whether the
1171 * server previously sent a non-empty session ID, and accepts the session
1174 * On failure, the context is marked as failed, and this function
1175 * returns 0. A possible failure condition is when no initial entropy
1176 * was injected, and none could be obtained from the OS (either OS
1177 * randomness gathering is not supported, or it failed).
1179 int br_ssl_client_reset(br_ssl_client_context
*cc
,
1180 const char *server_name
, int resume_session
);
1183 * Forget any session in the context. This means that the next handshake
1184 * that uses this context will necessarily be a full handshake (this
1185 * applies both to new connections and to renegotiations).
1188 br_ssl_client_forget_session(br_ssl_client_context
*cc
)
1190 cc
->eng
.session
.session_id_len
= 0;
1194 * Type for a "translated cipher suite", as an array of 16-bit integers:
1195 * first element is the cipher suite identifier (as used on the wire),
1196 * and the second element is the concatenation of four 4-bit elements which
1197 * characterise the cipher suite contents. In most to least significant
1198 * order, these 4-bit elements are:
1200 * Bits 12 to 15: key exchange + server key type
1201 * 0 RSA RSA key exchange, key is RSA (encryption)
1202 * 1 ECDHE-RSA ECDHE key exchange, key is RSA (signature)
1203 * 2 ECDHE-ECDSA ECDHE key exchange, key is EC (signature)
1204 * 3 ECDH-RSA Key is EC (key exchange), cert is signed with RSA
1205 * 4 ECDH-ECDSA Key is EC (key exchange), cert is signed with ECDSA
1207 * Bits 8 to 11: symmetric encryption algorithm
1213 * 5 ChaCha20/Poly1305
1215 * Bits 4 to 7: MAC algorithm
1216 * 0 AEAD No dedicated MAC because encryption is AEAD
1217 * 2 HMAC/SHA-1 Value matches br_sha1_ID
1218 * 4 HMAC/SHA-256 Value matches br_sha256_ID
1219 * 5 HMAC/SHA-384 Value matches br_sha384_ID
1221 * Bits 0 to 3: hash function for PRF when used with TLS-1.2
1222 * 4 SHA-256 Value matches br_sha256_ID
1223 * 5 SHA-384 Value matches br_sha384_ID
1225 typedef uint16_t br_suite_translated
[2];
1227 #define BR_SSLKEYX_RSA 0
1228 #define BR_SSLKEYX_ECDHE_RSA 1
1229 #define BR_SSLKEYX_ECDHE_ECDSA 2
1230 #define BR_SSLKEYX_ECDH_RSA 3
1231 #define BR_SSLKEYX_ECDH_ECDSA 4
1233 #define BR_SSLENC_3DES_CBC 0
1234 #define BR_SSLENC_AES128_CBC 1
1235 #define BR_SSLENC_AES256_CBC 2
1236 #define BR_SSLENC_AES128_GCM 3
1237 #define BR_SSLENC_AES256_GCM 4
1238 #define BR_SSLENC_CHACHA20 5
1240 #define BR_SSLMAC_AEAD 0
1241 #define BR_SSLMAC_SHA1 br_sha1_ID
1242 #define BR_SSLMAC_SHA256 br_sha256_ID
1243 #define BR_SSLMAC_SHA384 br_sha384_ID
1245 #define BR_SSLPRF_SHA256 br_sha256_ID
1246 #define BR_SSLPRF_SHA384 br_sha384_ID
1249 * Pre-declaration for the SSL server context.
1251 typedef struct br_ssl_server_context_ br_ssl_server_context
;
1254 * Type for the server policy choices, taken after analysis of the client
1257 * cipher_suite Cipher suite to use.
1259 * hash_id Signature hash function identifier (hash function
1260 * to use for signing the ServerKeyExchange, when the
1261 * suite uses ECDHE).
1263 * chain The certificate chain to send (number of certificates
1264 * chain_len is in chain_length). The certificates are send "as is"
1265 * and shall be in standard SSL/TLS order (i.e. end-entity
1266 * first, each subsequent certificate signs the previous).
1269 uint16_t cipher_suite
;
1271 const br_x509_certificate
*chain
;
1273 } br_ssl_server_choices
;
1276 * Type for the certificate and private key handler on the server: an
1277 * object with the following methods:
1279 * choose Select the parameters for this connection (cipher suite,
1280 * certificate chain...). The selection is written into the
1281 * '*choices' structure. Returned value is 1 on success, or
1282 * 0 on error (an error here means that the handshake will
1283 * fail, and a handshake_failure alert will be sent to the
1286 * do_keyx Perform the server-side key exchange operation. Returned
1287 * value is 1 on success, 0 on error (see below). This is
1288 * called only when the selected cipher suite calls for a
1289 * RSA or ECDH key exchange involving the server key.
1291 * do_sign Perform the server-side signature operation. Returned
1292 * value is the signature length, or 0 on error (see below).
1293 * This is called only when the selected cipher suite calls
1294 * for an ECDHE key exchange, signed by the server with its key.
1297 * The do_keyx() method shall apply the following semantics:
1299 * -- For RSA key exchange, it shall decrypt the incoming data along
1300 * the rules of PKCS#1 v1.5. The method must verify the proper padding
1301 * and also that the decrypted message length is exactly 48 bytes.
1302 * IMPORTANT: these operations MUST be constant-time (or adequatly blinded).
1303 * The decrypted message is written in the first 48 bytes of data[]. The
1304 * caller makes sure that the data[] buffer is large enough, and that 'len'
1305 * is at least 59 bytes.
1307 * -- For ECDH key exchange, the provided data is an EC point (uncompressed
1308 * format); the method shall multiply that point with the server private
1309 * key, and write the X coordinate of the resulting point in the data[]
1310 * buffer, starting at offset 1 (so if the method produces a compressed or
1311 * uncompressed point, form offset 0, then everything is fine).
1313 * In both cases, returned value is 1 on success, 0 on error.
1316 * The do_sign() method shall compute the signature on the hash value
1317 * provided in the data[] buffer. The 'hv_len' value contains the hash
1318 * value length, while the 'len' parameter is the total size of the
1319 * buffer. The method must verify that the signature length is no more
1320 * than 'len' bytes, and report an error otherwise.
1322 * The hash identifier is either 0 for the MD5+SHA-1 method in TLS-1.0 and
1323 * 1.1, or a non-zero hash function identifier in TLS-1.2 and later. In
1324 * the MD5+SHA-1 method, the hash value has length 36 bytes and there is
1325 * no hash function identifying header to add in the padding.
1327 * Returned value is the signature length (in bytes). On error, this method
1330 typedef struct br_ssl_server_policy_class_ br_ssl_server_policy_class
;
1331 struct br_ssl_server_policy_class_
{
1332 size_t context_size
;
1333 int (*choose
)(const br_ssl_server_policy_class
**pctx
,
1334 const br_ssl_server_context
*cc
,
1335 br_ssl_server_choices
*choices
);
1336 uint32_t (*do_keyx
)(const br_ssl_server_policy_class
**pctx
,
1337 unsigned char *data
, size_t len
);
1338 size_t (*do_sign
)(const br_ssl_server_policy_class
**pctx
,
1339 int hash_id
, size_t hv_len
, unsigned char *data
, size_t len
);
1343 * A single-chain RSA policy handler, that always uses a single chain and
1344 * a RSA key. It may be restricted to do only signatures or only key
1348 const br_ssl_server_policy_class
*vtable
;
1349 const br_x509_certificate
*chain
;
1351 const br_rsa_private_key
*sk
;
1352 unsigned allowed_usages
;
1353 br_rsa_private irsacore
;
1354 br_rsa_pkcs1_sign irsasign
;
1355 } br_ssl_server_policy_rsa_context
;
1358 * A single-chain EC policy handler, that always uses a single chain and
1359 * an EC key. It may be restricted to do only signatures or only key
1363 const br_ssl_server_policy_class
*vtable
;
1364 const br_x509_certificate
*chain
;
1366 const br_ec_private_key
*sk
;
1367 unsigned allowed_usages
;
1368 unsigned cert_issuer_key_type
;
1369 const br_multihash_context
*mhash
;
1370 const br_ec_impl
*iec
;
1371 br_ecdsa_sign iecdsa
;
1372 } br_ssl_server_policy_ec_context
;
1375 * Class type for a session parameter cache.
1377 * save Record session parameters. The session ID has been randomly
1378 * generated, and the session ID length is always 32 bytes.
1379 * The method shall copy the provided information (the structure
1382 * load Find session parameters by ID. The session ID is in the relevant
1383 * field in the '*params' structure, and has always length exactly
1384 * 32 bytes. The method shall fill in the other field with the
1385 * session data, if found. Returned value is 1 when the session was
1386 * found, 0 otherwise.
1388 * Note that the requesting server context is provided. Implementations
1389 * may used some of the resources of that context, e.g. random number
1390 * generator or implementations of some cryptographic algorithms.
1392 typedef struct br_ssl_session_cache_class_ br_ssl_session_cache_class
;
1393 struct br_ssl_session_cache_class_
{
1394 size_t context_size
;
1395 void (*save
)(const br_ssl_session_cache_class
**ctx
,
1396 br_ssl_server_context
*server_ctx
,
1397 const br_ssl_session_parameters
*params
);
1398 int (*load
)(const br_ssl_session_cache_class
**ctx
,
1399 br_ssl_server_context
*server_ctx
,
1400 br_ssl_session_parameters
*params
);
1404 * Context for a very basic cache system that uses a linked list, managed
1405 * with an LRU algorithm (when the cache is full and a new set of parameters
1406 * must be saved, the least recently used entry is evicted). The storage
1407 * buffer is externally provided. Internally, an index tree is used to
1408 * speed up operations.
1411 const br_ssl_session_cache_class
*vtable
;
1412 unsigned char *store
;
1413 size_t store_len
, store_ptr
;
1414 unsigned char index_key
[32];
1415 const br_hash_class
*hash
;
1417 uint32_t head
, tail
, root
;
1418 } br_ssl_session_cache_lru
;
1421 * Initialise a LRU session cache with the provided storage space.
1423 void br_ssl_session_cache_lru_init(br_ssl_session_cache_lru
*cc
,
1424 unsigned char *store
, size_t store_len
);
1427 * Context structure for a SSL server.
1429 struct br_ssl_server_context_
{
1431 * The encapsulated engine context.
1433 br_ssl_engine_context eng
;
1436 * Maximum version from the client.
1438 uint16_t client_max_version
;
1443 const br_ssl_session_cache_class
**cache_vtable
;
1446 * Translated cipher suites supported by the client. The list
1447 * is trimmed to include only the cipher suites that the
1448 * server also supports; they are in the same order as in the
1451 br_suite_translated client_suites
[BR_MAX_CIPHER_SUITES
];
1452 unsigned char client_suites_num
;
1455 * Hash functions supported by the client, with ECDSA and RSA
1456 * (bit mask). For hash function with id 'x', set bit index is
1457 * x for RSA, x+8 for ECDSA.
1462 * Curves supported by the client (bit mask, for named curves).
1467 * Context for chain handler.
1469 const br_ssl_server_policy_class
**policy_vtable
;
1470 const br_x509_certificate
*chain
;
1472 const unsigned char *cert_cur
;
1474 unsigned char sign_hash_id
;
1477 * For the core handlers, thus avoiding (in most cases) the
1478 * need for an externally provided policy context.
1481 const br_ssl_server_policy_class
*vtable
;
1482 br_ssl_server_policy_rsa_context single_rsa
;
1483 br_ssl_server_policy_ec_context single_ec
;
1487 * Buffer for the ECDHE private key.
1489 unsigned char ecdhe_key
[70];
1490 size_t ecdhe_key_len
;
1493 * Server-specific implementations.
1498 * If this flag is set, then the server will enforce its own cipher suite
1499 * preference order; otherwise, it follows the client preferences.
1501 #define BR_OPT_ENFORCE_SERVER_PREFERENCES ((uint32_t)1 << 0)
1504 * If this flag is set, then renegotiations are rejected unconditionally:
1505 * they won't be honoured if asked for programmatically, and requests from
1506 * the peer are rejected.
1508 #define BR_OPT_NO_RENEGOTIATION ((uint32_t)1 << 1)
1511 * Each br_ssl_server_init_xxx() function sets the list of supported
1512 * cipher suites and used implementations, as specified by the profile
1513 * name 'xxx'. Defined profile names are:
1515 * full_rsa all supported algorithm, server key type is RSA
1516 * full_ec all supported algorithm, server key type is EC
1517 * FIXME: add other profiles
1519 * Naming scheme for "minimal" profiles: min123
1521 * -- character 1: key exchange
1527 * -- character 2: version / PRF
1528 * 0 = TLS 1.0 / 1.1 with MD5+SHA-1
1529 * 2 = TLS 1.2 with SHA-256
1530 * 3 = TLS 1.2 with SHA-384
1531 * -- character 3: encryption
1537 void br_ssl_server_init_full_rsa(br_ssl_server_context
*cc
,
1538 const br_x509_certificate
*chain
, size_t chain_len
,
1539 const br_rsa_private_key
*sk
);
1541 void br_ssl_server_init_full_ec(br_ssl_server_context
*cc
,
1542 const br_x509_certificate
*chain
, size_t chain_len
,
1543 unsigned cert_issuer_key_type
, const br_ec_private_key
*sk
);
1545 void br_ssl_server_init_minr2g(br_ssl_server_context
*cc
,
1546 const br_x509_certificate
*chain
, size_t chain_len
,
1547 const br_rsa_private_key
*sk
);
1548 void br_ssl_server_init_mine2g(br_ssl_server_context
*cc
,
1549 const br_x509_certificate
*chain
, size_t chain_len
,
1550 const br_rsa_private_key
*sk
);
1551 void br_ssl_server_init_minf2g(br_ssl_server_context
*cc
,
1552 const br_x509_certificate
*chain
, size_t chain_len
,
1553 const br_ec_private_key
*sk
);
1554 void br_ssl_server_init_minu2g(br_ssl_server_context
*cc
,
1555 const br_x509_certificate
*chain
, size_t chain_len
,
1556 const br_ec_private_key
*sk
);
1557 void br_ssl_server_init_minv2g(br_ssl_server_context
*cc
,
1558 const br_x509_certificate
*chain
, size_t chain_len
,
1559 const br_ec_private_key
*sk
);
1562 * Get the supported client suites. The returned array is ordered by
1563 * client or server preferences, depending on the relevant flag.
1565 static inline const br_suite_translated
*
1566 br_ssl_server_get_client_suites(const br_ssl_server_context
*cc
, size_t *num
)
1568 *num
= cc
->client_suites_num
;
1569 return cc
->client_suites
;
1573 * Get the hash functions supported by the client. This is a field of
1574 * bits: for hash function of ID x, bit x is set if the hash function
1575 * is supported in RSA signatures, 8+x if it is supported with ECDSA.
1577 static inline uint16_t
1578 br_ssl_server_get_client_hashes(const br_ssl_server_context
*cc
)
1584 * Get the elliptic curves supported by the client. This is a bit field
1585 * (bit x is set if curve of ID x is supported).
1587 static inline uint32_t
1588 br_ssl_server_get_client_curves(const br_ssl_server_context
*cc
)
1594 * Clear the complete contents of a SSL server context, including the
1595 * reference to the configured buffer, implementations, cipher suites
1598 void br_ssl_server_zero(br_ssl_server_context
*cc
);
1601 * Set an externally provided policy context.
1604 br_ssl_server_set_policy(br_ssl_server_context
*cc
,
1605 const br_ssl_server_policy_class
**pctx
)
1607 cc
->policy_vtable
= pctx
;
1611 * Set the server certificate chain and key (single RSA case).
1612 * The 'allowed_usages' is a combination of usages, namely
1613 * BR_KEYTYPE_KEYX and/or BR_KEYTYPE_SIGN.
1615 void br_ssl_server_set_single_rsa(br_ssl_server_context
*cc
,
1616 const br_x509_certificate
*chain
, size_t chain_length
,
1617 const br_rsa_private_key
*sk
, unsigned allowed_usages
,
1618 br_rsa_private irsacore
, br_rsa_pkcs1_sign irsasign
);
1621 * Set the server certificate chain and key (single EC case).
1622 * The 'allowed_usages' is a combination of usages, namely
1623 * BR_KEYTYPE_KEYX and/or BR_KEYTYPE_SIGN.
1625 void br_ssl_server_set_single_ec(br_ssl_server_context
*cc
,
1626 const br_x509_certificate
*chain
, size_t chain_length
,
1627 const br_ec_private_key
*sk
, unsigned allowed_usages
,
1628 unsigned cert_issuer_key_type
,
1629 const br_ec_impl
*iec
, br_ecdsa_sign iecdsa
);
1632 * Configure the server context to use the provided cache for session
1636 br_ssl_server_set_cache(br_ssl_server_context
*cc
,
1637 const br_ssl_session_cache_class
**vtable
)
1639 cc
->cache_vtable
= vtable
;
1643 * Prepare or reset a server context for handling an incoming client.
1645 int br_ssl_server_reset(br_ssl_server_context
*cc
);
1647 /* ===================================================================== */
1650 * Context for the simplified I/O context. The transport medium is accessed
1651 * through the low_read() and low_write() callback functions, each with
1652 * its own opaque context pointer.
1654 * low_read() read some bytes, at most 'len' bytes, into data[]. The
1655 * returned value is the number of read bytes, or -1 on error.
1656 * The 'len' parameter is guaranteed never to exceed 20000,
1657 * so the length always fits in an 'int' on all platforms.
1659 * low_write() write up to 'len' bytes, to be read from data[]. The
1660 * returned value is the number of written bytes, or -1 on
1661 * error. The 'len' parameter is guaranteed never to exceed
1662 * 20000, so the length always fits in an 'int' on all
1665 * A socket closure (if the transport medium is a socket) should be reported
1666 * as an error (-1). The callbacks shall endeavour to block until at least
1667 * one byte can be read or written; a callback returning 0 at times is
1668 * acceptable, but this normally leads to the callback being immediately
1669 * called again, so the callback should at least always try to block for
1670 * some time if no I/O can take place.
1672 * The SSL engine naturally applies some buffering, so the callbacks need
1673 * not apply buffers of their own.
1676 br_ssl_engine_context
*engine
;
1677 int (*low_read
)(void *read_context
,
1678 unsigned char *data
, size_t len
);
1680 int (*low_write
)(void *write_context
,
1681 const unsigned char *data
, size_t len
);
1682 void *write_context
;
1686 * Initialise a simplified I/O context over the provided engine and
1689 void br_sslio_init(br_sslio_context
*ctx
,
1690 br_ssl_engine_context
*engine
,
1691 int (*low_read
)(void *read_context
,
1692 unsigned char *data
, size_t len
),
1694 int (*low_write
)(void *write_context
,
1695 const unsigned char *data
, size_t len
),
1696 void *write_context
);
1699 * Read some application data from a SSL connection. This call returns
1700 * only when at least one byte has been obtained. Returned value is
1701 * the number of bytes read, or -1 on error. The number of bytes
1702 * always fits on an 'int' (data from a single SSL/TLS record is
1705 * On error or SSL closure, this function returns -1. The caller should
1706 * inspect the error status on the SSL engine to distinguish between
1707 * normal closure and error.
1709 int br_sslio_read(br_sslio_context
*cc
, void *dst
, size_t len
);
1712 * Read some application data from a SSL connection. This call returns
1713 * only when ALL requested bytes have been read. Returned value is 0
1714 * on success, -1 on error. A normal SSL closure before that many bytes
1715 * are obtained is reported as an error by this function.
1717 int br_sslio_read_all(br_sslio_context
*cc
, void *dst
, size_t len
);
1720 * Write some application data onto a SSL connection. This call returns
1721 * only when at least one byte had been written onto the connection (but
1722 * not necessarily flushed). Returned value is the number of written
1723 * bytes, or -1 on error (error conditions include a closed connection).
1724 * It is guaranteed that the number of bytes written by such a call will
1725 * fit in an 'int' on all architectures.
1727 * Note that some written bytes may be buffered; use br_sslio_flush()
1728 * to make sure that the data is sent to the transport stream.
1730 int br_sslio_write(br_sslio_context
*cc
, const void *src
, size_t len
);
1733 * Write some application data onto a SSL connection. This call returns
1734 * only when ALL the bytes have been written onto the connection (but
1735 * not necessarily flushed). Returned value is 0 on success, -1 on error.
1737 * Note that some written bytes may be buffered; use br_sslio_flush()
1738 * to make sure that the data is sent to the transport stream.
1740 int br_sslio_write_all(br_sslio_context
*cc
, const void *src
, size_t len
);
1743 * Make sure that any buffered application data in the provided context
1744 * get packed up and sent unto the low_write() callback method. If that
1745 * callback method represents a buffered system, it is up to the caller
1746 * to then "flush" that system too.
1748 * Returned value is 0 on success, -1 on error.
1750 int br_sslio_flush(br_sslio_context
*cc
);
1753 * Perform a SSL close. This implies sending a close_notify, and reading
1754 * the response from the server. Returned value is 0 on success, -1 on
1757 int br_sslio_close(br_sslio_context
*cc
);
1759 /* ===================================================================== */
1762 * Symbolic constants for cipher suites.
1766 #define BR_TLS_NULL_WITH_NULL_NULL 0x0000
1767 #define BR_TLS_RSA_WITH_NULL_MD5 0x0001
1768 #define BR_TLS_RSA_WITH_NULL_SHA 0x0002
1769 #define BR_TLS_RSA_WITH_NULL_SHA256 0x003B
1770 #define BR_TLS_RSA_WITH_RC4_128_MD5 0x0004
1771 #define BR_TLS_RSA_WITH_RC4_128_SHA 0x0005
1772 #define BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA 0x000A
1773 #define BR_TLS_RSA_WITH_AES_128_CBC_SHA 0x002F
1774 #define BR_TLS_RSA_WITH_AES_256_CBC_SHA 0x0035
1775 #define BR_TLS_RSA_WITH_AES_128_CBC_SHA256 0x003C
1776 #define BR_TLS_RSA_WITH_AES_256_CBC_SHA256 0x003D
1777 #define BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 0x000D
1778 #define BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 0x0010
1779 #define BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 0x0013
1780 #define BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 0x0016
1781 #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA 0x0030
1782 #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA 0x0031
1783 #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA 0x0032
1784 #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA 0x0033
1785 #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA 0x0036
1786 #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA 0x0037
1787 #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA 0x0038
1788 #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x0039
1789 #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256 0x003E
1790 #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256 0x003F
1791 #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 0x0040
1792 #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 0x0067
1793 #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256 0x0068
1794 #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256 0x0069
1795 #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 0x006A
1796 #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 0x006B
1797 #define BR_TLS_DH_anon_WITH_RC4_128_MD5 0x0018
1798 #define BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 0x001B
1799 #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA 0x0034
1800 #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA 0x003A
1801 #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256 0x006C
1802 #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256 0x006D
1805 #define BR_TLS_ECDH_ECDSA_WITH_NULL_SHA 0xC001
1806 #define BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0xC002
1807 #define BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC003
1808 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0xC004
1809 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0xC005
1810 #define BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA 0xC006
1811 #define BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0xC007
1812 #define BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC008
1813 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0xC009
1814 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0xC00A
1815 #define BR_TLS_ECDH_RSA_WITH_NULL_SHA 0xC00B
1816 #define BR_TLS_ECDH_RSA_WITH_RC4_128_SHA 0xC00C
1817 #define BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0xC00D
1818 #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0xC00E
1819 #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0xC00F
1820 #define BR_TLS_ECDHE_RSA_WITH_NULL_SHA 0xC010
1821 #define BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA 0xC011
1822 #define BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0xC012
1823 #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0xC013
1824 #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC014
1825 #define BR_TLS_ECDH_anon_WITH_NULL_SHA 0xC015
1826 #define BR_TLS_ECDH_anon_WITH_RC4_128_SHA 0xC016
1827 #define BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 0xC017
1828 #define BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA 0xC018
1829 #define BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA 0xC019
1832 #define BR_TLS_RSA_WITH_AES_128_GCM_SHA256 0x009C
1833 #define BR_TLS_RSA_WITH_AES_256_GCM_SHA384 0x009D
1834 #define BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 0x009E
1835 #define BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 0x009F
1836 #define BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256 0x00A0
1837 #define BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384 0x00A1
1838 #define BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 0x00A2
1839 #define BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 0x00A3
1840 #define BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256 0x00A4
1841 #define BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384 0x00A5
1842 #define BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256 0x00A6
1843 #define BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384 0x00A7
1846 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023
1847 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024
1848 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC025
1849 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0xC026
1850 #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0xC027
1851 #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC028
1852 #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0xC029
1853 #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0xC02A
1854 #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B
1855 #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C
1856 #define BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 0xC02D
1857 #define BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 0xC02E
1858 #define BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC02F
1859 #define BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xC030
1860 #define BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 0xC031
1861 #define BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 0xC032
1864 #define BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8
1865 #define BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9
1866 #define BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCAA
1867 #define BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAB
1868 #define BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAC
1869 #define BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAD
1870 #define BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAE
1873 * Symbolic constants for alerts.
1875 #define BR_ALERT_CLOSE_NOTIFY 0
1876 #define BR_ALERT_UNEXPECTED_MESSAGE 10
1877 #define BR_ALERT_BAD_RECORD_MAC 20
1878 #define BR_ALERT_RECORD_OVERFLOW 22
1879 #define BR_ALERT_DECOMPRESSION_FAILURE 30
1880 #define BR_ALERT_HANDSHAKE_FAILURE 40
1881 #define BR_ALERT_BAD_CERTIFICATE 42
1882 #define BR_ALERT_UNSUPPORTED_CERTIFICATE 43
1883 #define BR_ALERT_CERTIFICATE_REVOKED 44
1884 #define BR_ALERT_CERTIFICATE_EXPIRED 45
1885 #define BR_ALERT_CERTIFICATE_UNKNOWN 46
1886 #define BR_ALERT_ILLEGAL_PARAMETER 47
1887 #define BR_ALERT_UNKNOWN_CA 48
1888 #define BR_ALERT_ACCESS_DENIED 49
1889 #define BR_ALERT_DECODE_ERROR 50
1890 #define BR_ALERT_DECRYPT_ERROR 51
1891 #define BR_ALERT_PROTOCOL_VERSION 70
1892 #define BR_ALERT_INSUFFICIENT_SECURITY 71
1893 #define BR_ALERT_INTERNAL_ERROR 80
1894 #define BR_ALERT_USER_CANCELED 90
1895 #define BR_ALERT_NO_RENEGOTIATION 100
1896 #define BR_ALERT_UNSUPPORTED_EXTENSION 110