Include dependency graph for bearssl_ssl.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	br_sslrec_in_class
	Decryption engine for SSL. More...

struct	br_sslrec_out_class
	Encryption engine for SSL. More...

struct	br_sslrec_out_clear_context
	Context for a no-encryption engine. More...

struct	br_sslrec_in_cbc_class
	Record decryption engine class, for CBC mode. More...

struct	br_sslrec_out_cbc_class
	Record encryption engine class, for CBC mode. More...

struct	br_sslrec_in_cbc_context
	Context structure for decrypting incoming records with CBC + HMAC. More...

struct	br_sslrec_out_cbc_context
	Context structure for encrypting outgoing records with CBC + HMAC. More...

struct	br_sslrec_in_gcm_class
	Record decryption engine class, for GCM mode. More...

struct	br_sslrec_out_gcm_class
	Record encryption engine class, for GCM mode. More...

struct	br_sslrec_gcm_context
	Context structure for processing records with GCM. More...

struct	br_sslrec_in_chapol_class
	Record decryption engine class, for ChaCha20+Poly1305. More...

struct	br_sslrec_out_chapol_class
	Record encryption engine class, for ChaCha20+Poly1305. More...

struct	br_sslrec_chapol_context
	Context structure for processing records with ChaCha20+Poly1305. More...

struct	br_sslrec_in_ccm_class
	Record decryption engine class, for CCM mode. More...

struct	br_sslrec_out_ccm_class
	Record encryption engine class, for CCM mode. More...

struct	br_sslrec_ccm_context
	Context structure for processing records with CCM. More...

struct	br_ssl_session_parameters
	Type for session parameters, to be saved for session resumption. More...

struct	br_ssl_engine_context
	Context structure for SSL engine. More...

struct	br_ssl_client_certificate
	Type for the client certificate, if requested by the server. More...

struct	br_ssl_client_certificate_class
	Class type for a certificate handler (client side). More...

struct	br_ssl_client_certificate_rsa_context
	A single-chain RSA client certificate handler. More...

struct	br_ssl_client_certificate_ec_context
	A single-chain EC client certificate handler. More...

struct	br_ssl_client_context
	Context structure for a SSL client. More...

struct	br_ssl_server_choices
	Type for the server policy choices, taken after analysis of the client message (ClientHello). More...

struct	br_ssl_server_policy_class
	Class type for a policy handler (server side). More...

struct	br_ssl_server_policy_rsa_context
	A single-chain RSA policy handler. More...

struct	br_ssl_server_policy_ec_context
	A single-chain EC policy handler. More...

struct	br_ssl_session_cache_class
	Class type for a session parameter cache. More...

struct	br_ssl_session_cache_lru
	Context for a basic cache system. More...

struct	br_ssl_server_context
	Context structure for a SSL server. More...

struct	br_sslio_context
	Context structure for the simplified SSL I/O wrapper. More...

Macros
#define	BR_SSL_BUFSIZE_INPUT (16384 + 325)
	Optimal input buffer size. More...

#define	BR_SSL_BUFSIZE_OUTPUT (16384 + 85)
	Optimal output buffer size. More...

#define	BR_SSL_BUFSIZE_MONO BR_SSL_BUFSIZE_INPUT
	Optimal buffer size for monodirectional engine (shared input/output buffer). More...

#define	BR_SSL_BUFSIZE_BIDI (BR_SSL_BUFSIZE_INPUT + BR_SSL_BUFSIZE_OUTPUT)
	Optimal buffer size for bidirectional engine (single buffer split into two separate input/output buffers). More...

#define	BR_SSL30 0x0300
	Protocol version: SSL 3.0 (unsupported). More...

#define	BR_TLS10 0x0301
	Protocol version: TLS 1.0. More...

#define	BR_TLS11 0x0302
	Protocol version: TLS 1.1. More...

#define	BR_TLS12 0x0303
	Protocol version: TLS 1.2. More...

#define	BR_ERR_OK 0
	SSL status: no error so far (0). More...

#define	BR_ERR_BAD_PARAM 1
	SSL status: caller-provided parameter is incorrect. More...

#define	BR_ERR_BAD_STATE 2
	SSL status: operation requested by the caller cannot be applied with the current context state (e.g. reading data while outgoing data is waiting to be sent). More...

#define	BR_ERR_UNSUPPORTED_VERSION 3
	SSL status: incoming protocol or record version is unsupported. More...

#define	BR_ERR_BAD_VERSION 4
	SSL status: incoming record version does not match the expected version. More...

#define	BR_ERR_BAD_LENGTH 5
	SSL status: incoming record length is invalid. More...

#define	BR_ERR_TOO_LARGE 6
	SSL status: incoming record is too large to be processed, or buffer is too small for the handshake message to send. More...

#define	BR_ERR_BAD_MAC 7
	SSL status: decryption found an invalid padding, or the record MAC is not correct. More...

#define	BR_ERR_NO_RANDOM 8
	SSL status: no initial entropy was provided, and none can be obtained from the OS. More...

#define	BR_ERR_UNKNOWN_TYPE 9
	SSL status: incoming record type is unknown. More...

#define	BR_ERR_UNEXPECTED 10
	SSL status: incoming record or message has wrong type with regards to the current engine state. More...

#define	BR_ERR_BAD_CCS 12
	SSL status: ChangeCipherSpec message from the peer has invalid contents. More...

#define	BR_ERR_BAD_ALERT 13
	SSL status: alert message from the peer has invalid contents (odd length). More...

#define	BR_ERR_BAD_HANDSHAKE 14
	SSL status: incoming handshake message decoding failed. More...

#define	BR_ERR_OVERSIZED_ID 15
	SSL status: ServerHello contains a session ID which is larger than 32 bytes. More...

#define	BR_ERR_BAD_CIPHER_SUITE 16
	SSL status: server wants to use a cipher suite that we did not claim to support. This is also reported if we tried to advertise a cipher suite that we do not support. More...

#define	BR_ERR_BAD_COMPRESSION 17
	SSL status: server wants to use a compression that we did not claim to support. More...

#define	BR_ERR_BAD_FRAGLEN 18
	SSL status: server's max fragment length does not match client's. More...

#define	BR_ERR_BAD_SECRENEG 19
	SSL status: secure renegotiation failed. More...

#define	BR_ERR_EXTRA_EXTENSION 20
	SSL status: server sent an extension type that we did not announce, or used the same extension type several times in a single ServerHello. More...

#define	BR_ERR_BAD_SNI 21
	SSL status: invalid Server Name Indication contents (when used by the server, this extension shall be empty). More...

#define	BR_ERR_BAD_HELLO_DONE 22
	SSL status: invalid ServerHelloDone from the server (length is not 0). More...

#define	BR_ERR_LIMIT_EXCEEDED 23
	SSL status: internal limit exceeded (e.g. server's public key is too large). More...

#define	BR_ERR_BAD_FINISHED 24
	SSL status: Finished message from peer does not match the expected value. More...

#define	BR_ERR_RESUME_MISMATCH 25
	SSL status: session resumption attempt with distinct version or cipher suite. More...

#define	BR_ERR_INVALID_ALGORITHM 26
	SSL status: unsupported or invalid algorithm (ECDHE curve, signature algorithm, hash function). More...

#define	BR_ERR_BAD_SIGNATURE 27
	SSL status: invalid signature (on ServerKeyExchange from server, or in CertificateVerify from client). More...

#define	BR_ERR_WRONG_KEY_USAGE 28
	SSL status: peer's public key does not have the proper type or is not allowed for requested operation. More...

#define	BR_ERR_NO_CLIENT_AUTH 29
	SSL status: client did not send a certificate upon request, or the client certificate could not be validated. More...

#define	BR_ERR_IO 31
	SSL status: I/O error or premature close on underlying transport stream. This error code is set only by the simplified I/O API ("br_sslio_*"). More...

#define	BR_ERR_RECV_FATAL_ALERT 256
	SSL status: base value for a received fatal alert. More...

#define	BR_ERR_SEND_FATAL_ALERT 512
	SSL status: base value for a sent fatal alert. More...

#define	BR_OPT_ENFORCE_SERVER_PREFERENCES ((uint32_t)1 << 0)
	Behavioural flag: enforce server preferences. More...

#define	BR_OPT_NO_RENEGOTIATION ((uint32_t)1 << 1)
	Behavioural flag: disable renegotiation. More...

#define	BR_OPT_TOLERATE_NO_CLIENT_AUTH ((uint32_t)1 << 2)
	Behavioural flag: tolerate lack of client authentication. More...

#define	BR_OPT_FAIL_ON_ALPN_MISMATCH ((uint32_t)1 << 3)
	Behavioural flag: fail on application protocol mismatch. More...

#define	BR_SSL_CLOSED 0x0001
	SSL engine state: closed or failed. More...

#define	BR_SSL_SENDREC 0x0002
	SSL engine state: record data is ready to be sent to the peer. More...

#define	BR_SSL_RECVREC 0x0004
	SSL engine state: engine may receive records from the peer. More...

#define	BR_SSL_SENDAPP 0x0008
	SSL engine state: engine may accept application data to send. More...

#define	BR_SSL_RECVAPP 0x0010
	SSL engine state: engine has received application data. More...

#define	BR_AUTH_ECDH 0
	Client authentication type: static ECDH. More...

#define	BR_AUTH_RSA 1
	Client authentication type: RSA signature. More...

#define	BR_AUTH_ECDSA 3
	Client authentication type: ECDSA signature. More...

#define	BR_TLS_NULL_WITH_NULL_NULL 0x0000

#define	BR_TLS_RSA_WITH_NULL_MD5 0x0001

#define	BR_TLS_RSA_WITH_NULL_SHA 0x0002

#define	BR_TLS_RSA_WITH_NULL_SHA256 0x003B

#define	BR_TLS_RSA_WITH_RC4_128_MD5 0x0004

#define	BR_TLS_RSA_WITH_RC4_128_SHA 0x0005

#define	BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA 0x000A

#define	BR_TLS_RSA_WITH_AES_128_CBC_SHA 0x002F

#define	BR_TLS_RSA_WITH_AES_256_CBC_SHA 0x0035

#define	BR_TLS_RSA_WITH_AES_128_CBC_SHA256 0x003C

#define	BR_TLS_RSA_WITH_AES_256_CBC_SHA256 0x003D

#define	BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 0x000D

#define	BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 0x0010

#define	BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 0x0013

#define	BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 0x0016

#define	BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA 0x0030

#define	BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA 0x0031

#define	BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA 0x0032

#define	BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA 0x0033

#define	BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA 0x0036

#define	BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA 0x0037

#define	BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA 0x0038

#define	BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x0039

#define	BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256 0x003E

#define	BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256 0x003F

#define	BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 0x0040

#define	BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 0x0067

#define	BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256 0x0068

#define	BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256 0x0069

#define	BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 0x006A

#define	BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 0x006B

#define	BR_TLS_DH_anon_WITH_RC4_128_MD5 0x0018

#define	BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 0x001B

#define	BR_TLS_DH_anon_WITH_AES_128_CBC_SHA 0x0034

#define	BR_TLS_DH_anon_WITH_AES_256_CBC_SHA 0x003A

#define	BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256 0x006C

#define	BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256 0x006D

#define	BR_TLS_ECDH_ECDSA_WITH_NULL_SHA 0xC001

#define	BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0xC002

#define	BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC003

#define	BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0xC004

#define	BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0xC005

#define	BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA 0xC006

#define	BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0xC007

#define	BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC008

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0xC009

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0xC00A

#define	BR_TLS_ECDH_RSA_WITH_NULL_SHA 0xC00B

#define	BR_TLS_ECDH_RSA_WITH_RC4_128_SHA 0xC00C

#define	BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0xC00D

#define	BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0xC00E

#define	BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0xC00F

#define	BR_TLS_ECDHE_RSA_WITH_NULL_SHA 0xC010

#define	BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA 0xC011

#define	BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0xC012

#define	BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0xC013

#define	BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC014

#define	BR_TLS_ECDH_anon_WITH_NULL_SHA 0xC015

#define	BR_TLS_ECDH_anon_WITH_RC4_128_SHA 0xC016

#define	BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 0xC017

#define	BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA 0xC018

#define	BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA 0xC019

#define	BR_TLS_RSA_WITH_AES_128_GCM_SHA256 0x009C

#define	BR_TLS_RSA_WITH_AES_256_GCM_SHA384 0x009D

#define	BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 0x009E

#define	BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 0x009F

#define	BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256 0x00A0

#define	BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384 0x00A1

#define	BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 0x00A2

#define	BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 0x00A3

#define	BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256 0x00A4

#define	BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384 0x00A5

#define	BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256 0x00A6

#define	BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384 0x00A7

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024

#define	BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC025

#define	BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0xC026

#define	BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0xC027

#define	BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC028

#define	BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0xC029

#define	BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0xC02A

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C

#define	BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 0xC02D

#define	BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 0xC02E

#define	BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC02F

#define	BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xC030

#define	BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 0xC031

#define	BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 0xC032

#define	BR_TLS_RSA_WITH_AES_128_CCM 0xC09C

#define	BR_TLS_RSA_WITH_AES_256_CCM 0xC09D

#define	BR_TLS_RSA_WITH_AES_128_CCM_8 0xC0A0

#define	BR_TLS_RSA_WITH_AES_256_CCM_8 0xC0A1

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM 0xC0AC

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM 0xC0AD

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 0xC0AE

#define	BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8 0xC0AF

#define	BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8

#define	BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9

#define	BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCAA

#define	BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAB

#define	BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAC

#define	BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAD

#define	BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAE

#define	BR_TLS_FALLBACK_SCSV 0x5600

#define	BR_ALERT_CLOSE_NOTIFY 0

#define	BR_ALERT_UNEXPECTED_MESSAGE 10

#define	BR_ALERT_BAD_RECORD_MAC 20

#define	BR_ALERT_RECORD_OVERFLOW 22

#define	BR_ALERT_DECOMPRESSION_FAILURE 30

#define	BR_ALERT_HANDSHAKE_FAILURE 40

#define	BR_ALERT_BAD_CERTIFICATE 42

#define	BR_ALERT_UNSUPPORTED_CERTIFICATE 43

#define	BR_ALERT_CERTIFICATE_REVOKED 44

#define	BR_ALERT_CERTIFICATE_EXPIRED 45

#define	BR_ALERT_CERTIFICATE_UNKNOWN 46

#define	BR_ALERT_ILLEGAL_PARAMETER 47

#define	BR_ALERT_UNKNOWN_CA 48

#define	BR_ALERT_ACCESS_DENIED 49

#define	BR_ALERT_DECODE_ERROR 50

#define	BR_ALERT_DECRYPT_ERROR 51

#define	BR_ALERT_PROTOCOL_VERSION 70

#define	BR_ALERT_INSUFFICIENT_SECURITY 71

#define	BR_ALERT_INTERNAL_ERROR 80

#define	BR_ALERT_USER_CANCELED 90

#define	BR_ALERT_NO_RENEGOTIATION 100

#define	BR_ALERT_UNSUPPORTED_EXTENSION 110

#define	BR_ALERT_NO_APPLICATION_PROTOCOL 120

Typedefs
typedef uint16_t	br_suite_translated[2]
	Type for a "translated cipher suite", as an array of two 16-bit integers. More...

Functions
static uint32_t	br_ssl_engine_get_flags (br_ssl_engine_context *cc)
	Get currently defined engine behavioural flags. More...

static void	br_ssl_engine_set_all_flags (br_ssl_engine_context *cc, uint32_t flags)
	Set all engine behavioural flags. More...

static void	br_ssl_engine_add_flags (br_ssl_engine_context *cc, uint32_t flags)
	Set some engine behavioural flags. More...

static void	br_ssl_engine_remove_flags (br_ssl_engine_context *cc, uint32_t flags)
	Clear some engine behavioural flags. More...

static void	br_ssl_engine_set_versions (br_ssl_engine_context *cc, unsigned version_min, unsigned version_max)
	Set the minimum and maximum supported protocol versions. More...

void	br_ssl_engine_set_suites (br_ssl_engine_context cc, const uint16_t suites, size_t suites_num)
	Set the list of cipher suites advertised by this context. More...

static void	br_ssl_engine_set_x509 (br_ssl_engine_context cc, const br_x509_class *x509ctx)
	Set the X.509 engine. More...

static void	br_ssl_engine_set_protocol_names (br_ssl_engine_context ctx, const char *names, size_t num)
	Set the supported protocol names. More...

static const char *	br_ssl_engine_get_selected_protocol (br_ssl_engine_context *ctx)
	Get the selected protocol. More...

static void	br_ssl_engine_set_hash (br_ssl_engine_context ctx, int id, const br_hash_class impl)
	Set a hash function implementation (by ID). More...

static const br_hash_class *	br_ssl_engine_get_hash (br_ssl_engine_context *ctx, int id)
	Get a hash function implementation (by ID). More...

static void	br_ssl_engine_set_prf10 (br_ssl_engine_context *cc, br_tls_prf_impl impl)
	Set the PRF implementation (for TLS 1.0 and 1.1). More...

static void	br_ssl_engine_set_prf_sha256 (br_ssl_engine_context *cc, br_tls_prf_impl impl)
	Set the PRF implementation with SHA-256 (for TLS 1.2). More...

static void	br_ssl_engine_set_prf_sha384 (br_ssl_engine_context *cc, br_tls_prf_impl impl)
	Set the PRF implementation with SHA-384 (for TLS 1.2). More...

static void	br_ssl_engine_set_aes_cbc (br_ssl_engine_context cc, const br_block_cbcenc_class impl_enc, const br_block_cbcdec_class *impl_dec)
	Set the AES/CBC implementations. More...

void	br_ssl_engine_set_default_aes_cbc (br_ssl_engine_context *cc)
	Set the "default" AES/CBC implementations. More...

static void	br_ssl_engine_set_aes_ctr (br_ssl_engine_context cc, const br_block_ctr_class impl)
	Set the AES/CTR implementation. More...

void	br_ssl_engine_set_default_aes_gcm (br_ssl_engine_context *cc)
	Set the "default" implementations for AES/GCM (AES/CTR + GHASH). More...

static void	br_ssl_engine_set_des_cbc (br_ssl_engine_context cc, const br_block_cbcenc_class impl_enc, const br_block_cbcdec_class *impl_dec)
	Set the DES/CBC implementations. More...

void	br_ssl_engine_set_default_des_cbc (br_ssl_engine_context *cc)
	Set the "default" DES/CBC implementations. More...

static void	br_ssl_engine_set_ghash (br_ssl_engine_context *cc, br_ghash impl)
	Set the GHASH implementation (used in GCM mode). More...

static void	br_ssl_engine_set_chacha20 (br_ssl_engine_context *cc, br_chacha20_run ichacha)
	Set the ChaCha20 implementation. More...

static void	br_ssl_engine_set_poly1305 (br_ssl_engine_context *cc, br_poly1305_run ipoly)
	Set the Poly1305 implementation. More...

void	br_ssl_engine_set_default_chapol (br_ssl_engine_context *cc)
	Set the "default" ChaCha20 and Poly1305 implementations. More...

static void	br_ssl_engine_set_aes_ctrcbc (br_ssl_engine_context cc, const br_block_ctrcbc_class impl)
	Set the AES/CTR+CBC implementation. More...

void	br_ssl_engine_set_default_aes_ccm (br_ssl_engine_context *cc)
	Set the "default" implementations for AES/CCM. More...

static void	br_ssl_engine_set_cbc (br_ssl_engine_context cc, const br_sslrec_in_cbc_class impl_in, const br_sslrec_out_cbc_class *impl_out)
	Set the record encryption and decryption engines for CBC + HMAC. More...

static void	br_ssl_engine_set_gcm (br_ssl_engine_context cc, const br_sslrec_in_gcm_class impl_in, const br_sslrec_out_gcm_class *impl_out)
	Set the record encryption and decryption engines for GCM. More...

static void	br_ssl_engine_set_ccm (br_ssl_engine_context cc, const br_sslrec_in_ccm_class impl_in, const br_sslrec_out_ccm_class *impl_out)
	Set the record encryption and decryption engines for CCM. More...

static void	br_ssl_engine_set_chapol (br_ssl_engine_context cc, const br_sslrec_in_chapol_class impl_in, const br_sslrec_out_chapol_class *impl_out)
	Set the record encryption and decryption engines for ChaCha20+Poly1305. More...

static void	br_ssl_engine_set_ec (br_ssl_engine_context cc, const br_ec_impl iec)
	Set the EC implementation. More...

void	br_ssl_engine_set_default_ec (br_ssl_engine_context *cc)
	Set the "default" EC implementation. More...

static const br_ec_impl *	br_ssl_engine_get_ec (br_ssl_engine_context *cc)
	Get the EC implementation configured in the provided engine. More...

static void	br_ssl_engine_set_rsavrfy (br_ssl_engine_context *cc, br_rsa_pkcs1_vrfy irsavrfy)
	Set the RSA signature verification implementation. More...

void	br_ssl_engine_set_default_rsavrfy (br_ssl_engine_context *cc)
	Set the "default" RSA implementation (signature verification). More...

static br_rsa_pkcs1_vrfy	br_ssl_engine_get_rsavrfy (br_ssl_engine_context *cc)
	Get the RSA implementation (signature verification) configured in the provided engine. More...

static void	br_ssl_engine_set_ecdsa (br_ssl_engine_context *cc, br_ecdsa_vrfy iecdsa)

void	br_ssl_engine_set_default_ecdsa (br_ssl_engine_context *cc)
	Set the "default" ECDSA implementation (signature verification). More...

static br_ecdsa_vrfy	br_ssl_engine_get_ecdsa (br_ssl_engine_context *cc)
	Get the ECDSA implementation (signature verification) configured in the provided engine. More...

void	br_ssl_engine_set_buffer (br_ssl_engine_context cc, void iobuf, size_t iobuf_len, int bidi)
	Set the I/O buffer for the SSL engine. More...

void	br_ssl_engine_set_buffers_bidi (br_ssl_engine_context cc, void ibuf, size_t ibuf_len, void *obuf, size_t obuf_len)
	Set the I/O buffers for the SSL engine. More...

void	br_ssl_engine_inject_entropy (br_ssl_engine_context cc, const void data, size_t len)
	Inject some "initial entropy" in the context. More...

static const char *	br_ssl_engine_get_server_name (const br_ssl_engine_context *cc)
	Get the "server name" in this engine. More...

static unsigned	br_ssl_engine_get_version (const br_ssl_engine_context *cc)
	Get the protocol version. More...

static void	br_ssl_engine_get_session_parameters (const br_ssl_engine_context cc, br_ssl_session_parameters pp)
	Get a copy of the session parameters. More...

static void	br_ssl_engine_set_session_parameters (br_ssl_engine_context cc, const br_ssl_session_parameters pp)
	Set the session parameters to the provided values. More...

static int	br_ssl_engine_get_ecdhe_curve (br_ssl_engine_context *cc)
	Get identifier for the curve used for key exchange. More...

unsigned	br_ssl_engine_current_state (const br_ssl_engine_context *cc)
	Get the current engine state. More...

static int	br_ssl_engine_last_error (const br_ssl_engine_context *cc)
	Get the engine error indicator. More...

unsigned char *	br_ssl_engine_sendapp_buf (const br_ssl_engine_context cc, size_t len)
	Get buffer for application data to send. More...

void	br_ssl_engine_sendapp_ack (br_ssl_engine_context *cc, size_t len)
	Inform the engine of some new application data. More...

unsigned char *	br_ssl_engine_recvapp_buf (const br_ssl_engine_context cc, size_t len)
	Get buffer for received application data. More...

void	br_ssl_engine_recvapp_ack (br_ssl_engine_context *cc, size_t len)
	Acknowledge some received application data. More...

unsigned char *	br_ssl_engine_sendrec_buf (const br_ssl_engine_context cc, size_t len)
	Get buffer for record data to send. More...

void	br_ssl_engine_sendrec_ack (br_ssl_engine_context *cc, size_t len)
	Acknowledge some sent record data. More...

unsigned char *	br_ssl_engine_recvrec_buf (const br_ssl_engine_context cc, size_t len)
	Get buffer for incoming records. More...

void	br_ssl_engine_recvrec_ack (br_ssl_engine_context *cc, size_t len)
	Inform the engine of some new record data. More...

void	br_ssl_engine_flush (br_ssl_engine_context *cc, int force)
	Flush buffered application data. More...

void	br_ssl_engine_close (br_ssl_engine_context *cc)
	Initiate a closure. More...

int	br_ssl_engine_renegotiate (br_ssl_engine_context *cc)
	Initiate a renegotiation. More...

int	br_ssl_key_export (br_ssl_engine_context cc, void dst, size_t len, const char label, const void context, size_t context_len)
	Export key material from a connected SSL engine (RFC 5705). More...

static uint32_t	br_ssl_client_get_server_hashes (const br_ssl_client_context *cc)
	Get the hash functions and signature algorithms supported by the server. More...

static int	br_ssl_client_get_server_curve (const br_ssl_client_context *cc)
	Get the server key curve. More...

void	br_ssl_client_init_full (br_ssl_client_context cc, br_x509_minimal_context xc, const br_x509_trust_anchor *trust_anchors, size_t trust_anchors_num)
	SSL client profile: full. More...

void	br_ssl_client_zero (br_ssl_client_context *cc)
	Clear the complete contents of a SSL client context. More...

static void	br_ssl_client_set_client_certificate (br_ssl_client_context cc, const br_ssl_client_certificate_class *pctx)
	Set an externally provided client certificate handler context. More...

static void	br_ssl_client_set_rsapub (br_ssl_client_context *cc, br_rsa_public irsapub)
	Set the RSA public-key operations implementation. More...

void	br_ssl_client_set_default_rsapub (br_ssl_client_context *cc)
	Set the "default" RSA implementation for public-key operations. More...

static void	br_ssl_client_set_min_clienthello_len (br_ssl_client_context *cc, uint16_t len)
	Set the minimum ClientHello length (RFC 7685 padding). More...

int	br_ssl_client_reset (br_ssl_client_context cc, const char server_name, int resume_session)
	Prepare or reset a client context for a new connection. More...

static void	br_ssl_client_forget_session (br_ssl_client_context *cc)
	Forget any session in the context. More...

void	br_ssl_client_set_single_rsa (br_ssl_client_context cc, const br_x509_certificate chain, size_t chain_len, const br_rsa_private_key *sk, br_rsa_pkcs1_sign irsasign)
	Set client certificate chain and key (single RSA case). More...

void	br_ssl_client_set_single_ec (br_ssl_client_context cc, const br_x509_certificate chain, size_t chain_len, const br_ec_private_key sk, unsigned allowed_usages, unsigned cert_issuer_key_type, const br_ec_impl iec, br_ecdsa_sign iecdsa)

void	br_ssl_session_cache_lru_init (br_ssl_session_cache_lru cc, unsigned char store, size_t store_len)
	Initialise a LRU session cache with the provided storage space. More...

void	br_ssl_session_cache_lru_forget (br_ssl_session_cache_lru cc, const unsigned char id)
	Forget an entry in an LRU session cache. More...

void	br_ssl_server_init_full_rsa (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_rsa_private_key *sk)
	SSL server profile: full_rsa. More...

void	br_ssl_server_init_full_ec (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, unsigned cert_issuer_key_type, const br_ec_private_key *sk)
	SSL server profile: full_ec. More...

void	br_ssl_server_init_minr2g (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_rsa_private_key *sk)
	SSL server profile: minr2g. More...

void	br_ssl_server_init_mine2g (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_rsa_private_key *sk)
	SSL server profile: mine2g. More...

void	br_ssl_server_init_minf2g (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_ec_private_key *sk)
	SSL server profile: minf2g. More...

void	br_ssl_server_init_minu2g (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_ec_private_key *sk)
	SSL server profile: minu2g. More...

void	br_ssl_server_init_minv2g (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_ec_private_key *sk)
	SSL server profile: minv2g. More...

void	br_ssl_server_init_mine2c (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_rsa_private_key *sk)
	SSL server profile: mine2c. More...

void	br_ssl_server_init_minf2c (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_ec_private_key *sk)
	SSL server profile: minf2c. More...

static const br_suite_translated *	br_ssl_server_get_client_suites (const br_ssl_server_context cc, size_t num)
	Get the supported client suites. More...

static uint32_t	br_ssl_server_get_client_hashes (const br_ssl_server_context *cc)
	Get the hash functions and signature algorithms supported by the client. More...

static uint32_t	br_ssl_server_get_client_curves (const br_ssl_server_context *cc)
	Get the elliptic curves supported by the client. More...

void	br_ssl_server_zero (br_ssl_server_context *cc)
	Clear the complete contents of a SSL server context. More...

static void	br_ssl_server_set_policy (br_ssl_server_context cc, const br_ssl_server_policy_class *pctx)
	Set an externally provided policy context. More...

void	br_ssl_server_set_single_rsa (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_rsa_private_key *sk, unsigned allowed_usages, br_rsa_private irsacore, br_rsa_pkcs1_sign irsasign)
	Set the server certificate chain and key (single RSA case). More...

void	br_ssl_server_set_single_ec (br_ssl_server_context cc, const br_x509_certificate chain, size_t chain_len, const br_ec_private_key sk, unsigned allowed_usages, unsigned cert_issuer_key_type, const br_ec_impl iec, br_ecdsa_sign iecdsa)
	Set the server certificate chain and key (single EC case). More...

static void	br_ssl_server_set_trust_anchor_names (br_ssl_server_context cc, const br_x500_name ta_names, size_t num)
	Activate client certificate authentication. More...

static void	br_ssl_server_set_trust_anchor_names_alt (br_ssl_server_context cc, const br_x509_trust_anchor tas, size_t num)
	Activate client certificate authentication. More...

static void	br_ssl_server_set_cache (br_ssl_server_context cc, const br_ssl_session_cache_class *vtable)
	Configure the cache for session parameters. More...

int	br_ssl_server_reset (br_ssl_server_context *cc)
	Prepare or reset a server context for handling an incoming client. More...

void	br_sslio_init (br_sslio_context ctx, br_ssl_engine_context engine, int(low_read)(void read_context, unsigned char data, size_t len), void read_context, int(low_write)(void write_context, const unsigned char data, size_t len), void write_context)
	Initialise a simplified I/O wrapper context. More...

int	br_sslio_read (br_sslio_context cc, void dst, size_t len)
	Read some application data from a SSL connection. More...

int	br_sslio_read_all (br_sslio_context cc, void dst, size_t len)
	Read application data from a SSL connection. More...

int	br_sslio_write (br_sslio_context cc, const void src, size_t len)
	Write some application data unto a SSL connection. More...

int	br_sslio_write_all (br_sslio_context cc, const void src, size_t len)
	Write application data unto a SSL connection. More...

int	br_sslio_flush (br_sslio_context *cc)
	Flush pending data. More...

int	br_sslio_close (br_sslio_context *cc)
	Close the SSL connection. More...

Variables
const br_sslrec_out_class	br_sslrec_out_clear_vtable
	Static, constant vtable for the no-encryption engine. More...

const br_sslrec_in_cbc_class	br_sslrec_in_cbc_vtable
	Static, constant vtable for record decryption with CBC. More...

const br_sslrec_out_cbc_class	br_sslrec_out_cbc_vtable
	Static, constant vtable for record encryption with CBC. More...

const br_sslrec_in_gcm_class	br_sslrec_in_gcm_vtable
	Static, constant vtable for record decryption with GCM. More...

const br_sslrec_out_gcm_class	br_sslrec_out_gcm_vtable
	Static, constant vtable for record encryption with GCM. More...

const br_sslrec_in_chapol_class	br_sslrec_in_chapol_vtable
	Static, constant vtable for record decryption with ChaCha20+Poly1305. More...

const br_sslrec_out_chapol_class	br_sslrec_out_chapol_vtable
	Static, constant vtable for record encryption with ChaCha20+Poly1305. More...

const br_sslrec_in_ccm_class	br_sslrec_in_ccm_vtable
	Static, constant vtable for record decryption with CCM. More...

const br_sslrec_out_ccm_class	br_sslrec_out_ccm_vtable
	Static, constant vtable for record encryption with CCM. More...

Detailed Description

SSL

For an overview of the SSL/TLS API, see the BearSSL Web site.

The BR_TLS_* constants correspond to the standard cipher suites and their values in the IANA registry.

The BR_ALERT_* constants are for standard TLS alert messages. When a fatal alert message is sent of received, then the SSL engine context status is set to the sum of that alert value (an integer in the 0..255 range) and a fixed offset (BR_ERR_SEND_FATAL_ALERT for a sent alert, BR_ERR_RECV_FATAL_ALERT for a received alert).

Macro Definition Documentation

◆ BR_ALERT_ACCESS_DENIED

#define BR_ALERT_ACCESS_DENIED 49

◆ BR_ALERT_BAD_CERTIFICATE

#define BR_ALERT_BAD_CERTIFICATE 42

◆ BR_ALERT_BAD_RECORD_MAC

#define BR_ALERT_BAD_RECORD_MAC 20

◆ BR_ALERT_CERTIFICATE_EXPIRED

#define BR_ALERT_CERTIFICATE_EXPIRED 45

◆ BR_ALERT_CERTIFICATE_REVOKED

#define BR_ALERT_CERTIFICATE_REVOKED 44

◆ BR_ALERT_CERTIFICATE_UNKNOWN

#define BR_ALERT_CERTIFICATE_UNKNOWN 46

◆ BR_ALERT_CLOSE_NOTIFY

#define BR_ALERT_CLOSE_NOTIFY 0

◆ BR_ALERT_DECODE_ERROR

#define BR_ALERT_DECODE_ERROR 50

◆ BR_ALERT_DECOMPRESSION_FAILURE

#define BR_ALERT_DECOMPRESSION_FAILURE 30

◆ BR_ALERT_DECRYPT_ERROR

#define BR_ALERT_DECRYPT_ERROR 51

◆ BR_ALERT_HANDSHAKE_FAILURE

#define BR_ALERT_HANDSHAKE_FAILURE 40

◆ BR_ALERT_ILLEGAL_PARAMETER

#define BR_ALERT_ILLEGAL_PARAMETER 47

◆ BR_ALERT_INSUFFICIENT_SECURITY

#define BR_ALERT_INSUFFICIENT_SECURITY 71

◆ BR_ALERT_INTERNAL_ERROR

#define BR_ALERT_INTERNAL_ERROR 80

◆ BR_ALERT_NO_APPLICATION_PROTOCOL

#define BR_ALERT_NO_APPLICATION_PROTOCOL 120

◆ BR_ALERT_NO_RENEGOTIATION

#define BR_ALERT_NO_RENEGOTIATION 100

◆ BR_ALERT_PROTOCOL_VERSION

#define BR_ALERT_PROTOCOL_VERSION 70

◆ BR_ALERT_RECORD_OVERFLOW

#define BR_ALERT_RECORD_OVERFLOW 22

◆ BR_ALERT_UNEXPECTED_MESSAGE

#define BR_ALERT_UNEXPECTED_MESSAGE 10

◆ BR_ALERT_UNKNOWN_CA

#define BR_ALERT_UNKNOWN_CA 48

◆ BR_ALERT_UNSUPPORTED_CERTIFICATE

#define BR_ALERT_UNSUPPORTED_CERTIFICATE 43

◆ BR_ALERT_UNSUPPORTED_EXTENSION

#define BR_ALERT_UNSUPPORTED_EXTENSION 110

◆ BR_ALERT_USER_CANCELED

#define BR_ALERT_USER_CANCELED 90

◆ BR_AUTH_ECDH

#define BR_AUTH_ECDH 0

Client authentication type: static ECDH.

◆ BR_AUTH_ECDSA

#define BR_AUTH_ECDSA 3

Client authentication type: ECDSA signature.

◆ BR_AUTH_RSA

#define BR_AUTH_RSA 1

Client authentication type: RSA signature.

◆ BR_ERR_BAD_ALERT

#define BR_ERR_BAD_ALERT 13

SSL status: alert message from the peer has invalid contents (odd length).

◆ BR_ERR_BAD_CCS

#define BR_ERR_BAD_CCS 12

SSL status: ChangeCipherSpec message from the peer has invalid contents.

◆ BR_ERR_BAD_CIPHER_SUITE

#define BR_ERR_BAD_CIPHER_SUITE 16

SSL status: server wants to use a cipher suite that we did not claim to support. This is also reported if we tried to advertise a cipher suite that we do not support.

◆ BR_ERR_BAD_COMPRESSION

#define BR_ERR_BAD_COMPRESSION 17

SSL status: server wants to use a compression that we did not claim to support.

◆ BR_ERR_BAD_FINISHED

#define BR_ERR_BAD_FINISHED 24

SSL status: Finished message from peer does not match the expected value.

◆ BR_ERR_BAD_FRAGLEN

#define BR_ERR_BAD_FRAGLEN 18

SSL status: server's max fragment length does not match client's.

◆ BR_ERR_BAD_HANDSHAKE

#define BR_ERR_BAD_HANDSHAKE 14

SSL status: incoming handshake message decoding failed.

◆ BR_ERR_BAD_HELLO_DONE

#define BR_ERR_BAD_HELLO_DONE 22

SSL status: invalid ServerHelloDone from the server (length is not 0).

◆ BR_ERR_BAD_LENGTH

#define BR_ERR_BAD_LENGTH 5

SSL status: incoming record length is invalid.

◆ BR_ERR_BAD_MAC

#define BR_ERR_BAD_MAC 7

SSL status: decryption found an invalid padding, or the record MAC is not correct.

◆ BR_ERR_BAD_PARAM

#define BR_ERR_BAD_PARAM 1

SSL status: caller-provided parameter is incorrect.

◆ BR_ERR_BAD_SECRENEG

#define BR_ERR_BAD_SECRENEG 19

SSL status: secure renegotiation failed.

◆ BR_ERR_BAD_SIGNATURE

#define BR_ERR_BAD_SIGNATURE 27

SSL status: invalid signature (on ServerKeyExchange from server, or in CertificateVerify from client).

◆ BR_ERR_BAD_SNI

#define BR_ERR_BAD_SNI 21

SSL status: invalid Server Name Indication contents (when used by the server, this extension shall be empty).

◆ BR_ERR_BAD_STATE

#define BR_ERR_BAD_STATE 2

SSL status: operation requested by the caller cannot be applied with the current context state (e.g. reading data while outgoing data is waiting to be sent).

◆ BR_ERR_BAD_VERSION

#define BR_ERR_BAD_VERSION 4

SSL status: incoming record version does not match the expected version.

◆ BR_ERR_EXTRA_EXTENSION

#define BR_ERR_EXTRA_EXTENSION 20

SSL status: server sent an extension type that we did not announce, or used the same extension type several times in a single ServerHello.

◆ BR_ERR_INVALID_ALGORITHM

#define BR_ERR_INVALID_ALGORITHM 26

SSL status: unsupported or invalid algorithm (ECDHE curve, signature algorithm, hash function).

◆ BR_ERR_IO

#define BR_ERR_IO 31

SSL status: I/O error or premature close on underlying transport stream. This error code is set only by the simplified I/O API ("br_sslio_*").

◆ BR_ERR_LIMIT_EXCEEDED

#define BR_ERR_LIMIT_EXCEEDED 23

SSL status: internal limit exceeded (e.g. server's public key is too large).

◆ BR_ERR_NO_CLIENT_AUTH

#define BR_ERR_NO_CLIENT_AUTH 29

SSL status: client did not send a certificate upon request, or the client certificate could not be validated.

◆ BR_ERR_NO_RANDOM

#define BR_ERR_NO_RANDOM 8

SSL status: no initial entropy was provided, and none can be obtained from the OS.

◆ BR_ERR_OK

#define BR_ERR_OK 0

SSL status: no error so far (0).

◆ BR_ERR_OVERSIZED_ID

#define BR_ERR_OVERSIZED_ID 15

SSL status: ServerHello contains a session ID which is larger than 32 bytes.

◆ BR_ERR_RECV_FATAL_ALERT

#define BR_ERR_RECV_FATAL_ALERT 256

SSL status: base value for a received fatal alert.

When a fatal alert is received from the peer, the alert value is added to this constant.

◆ BR_ERR_RESUME_MISMATCH

#define BR_ERR_RESUME_MISMATCH 25

SSL status: session resumption attempt with distinct version or cipher suite.

◆ BR_ERR_SEND_FATAL_ALERT

#define BR_ERR_SEND_FATAL_ALERT 512

SSL status: base value for a sent fatal alert.

When a fatal alert is sent to the peer, the alert value is added to this constant.

◆ BR_ERR_TOO_LARGE

#define BR_ERR_TOO_LARGE 6

SSL status: incoming record is too large to be processed, or buffer is too small for the handshake message to send.

◆ BR_ERR_UNEXPECTED

#define BR_ERR_UNEXPECTED 10

SSL status: incoming record or message has wrong type with regards to the current engine state.

◆ BR_ERR_UNKNOWN_TYPE

#define BR_ERR_UNKNOWN_TYPE 9

SSL status: incoming record type is unknown.

◆ BR_ERR_UNSUPPORTED_VERSION

#define BR_ERR_UNSUPPORTED_VERSION 3

SSL status: incoming protocol or record version is unsupported.

◆ BR_ERR_WRONG_KEY_USAGE

#define BR_ERR_WRONG_KEY_USAGE 28

SSL status: peer's public key does not have the proper type or is not allowed for requested operation.

◆ BR_OPT_ENFORCE_SERVER_PREFERENCES

#define BR_OPT_ENFORCE_SERVER_PREFERENCES ((uint32_t)1 << 0)

Behavioural flag: enforce server preferences.

If this flag is set, then the server will enforce its own cipher suite preference order; otherwise, it follows the client preferences.

◆ BR_OPT_FAIL_ON_ALPN_MISMATCH

#define BR_OPT_FAIL_ON_ALPN_MISMATCH ((uint32_t)1 << 3)

Behavioural flag: fail on application protocol mismatch.

The ALPN extension (RFC 7301) allows the client to send a list of application protocol names, and the server to select one. A mismatch is one of the following occurrences:

On the client: the client sends a list of names, the server responds with a protocol name which is not part of the list of names sent by the client.
On the server: the client sends a list of names, and the server is also configured with a list of names, but there is no common protocol name between the two lists.

Normal behaviour in case of mismatch is to report no matching name (br_ssl_engine_get_selected_protocol() returns NULL) and carry on. If the flag is set, then a mismatch implies a protocol failure (if the mismatch is detected by the server, it will send a fatal alert).

Note: even with this flag, br_ssl_engine_get_selected_protocol() may still return NULL if the client or the server does not send an ALPN extension at all.

◆ BR_OPT_NO_RENEGOTIATION

#define BR_OPT_NO_RENEGOTIATION ((uint32_t)1 << 1)

Behavioural flag: disable renegotiation.

If this flag is set, then renegotiations are rejected unconditionally: they won't be honoured if asked for programmatically, and requests from the peer are rejected.

◆ BR_OPT_TOLERATE_NO_CLIENT_AUTH

#define BR_OPT_TOLERATE_NO_CLIENT_AUTH ((uint32_t)1 << 2)

Behavioural flag: tolerate lack of client authentication.

If this flag is set in a server and the server requests a client certificate, but the authentication fails (the client does not send a certificate, or the client's certificate chain cannot be validated), then the connection keeps on. Without this flag, a failed client authentication terminates the connection.

Notes:

If the client's certificate can be validated and its public key is supported, then a wrong signature value terminates the connection regardless of that flag.
If using full-static ECDH, then a failure to validate the client's certificate prevents the handshake from succeeding.

◆ BR_SSL30

#define BR_SSL30 0x0300

Protocol version: SSL 3.0 (unsupported).

◆ BR_SSL_BUFSIZE_BIDI

#define BR_SSL_BUFSIZE_BIDI (BR_SSL_BUFSIZE_INPUT + BR_SSL_BUFSIZE_OUTPUT)

Optimal buffer size for bidirectional engine (single buffer split into two separate input/output buffers).

◆ BR_SSL_BUFSIZE_INPUT

#define BR_SSL_BUFSIZE_INPUT (16384 + 325)

Optimal input buffer size.

◆ BR_SSL_BUFSIZE_MONO

#define BR_SSL_BUFSIZE_MONO BR_SSL_BUFSIZE_INPUT

Optimal buffer size for monodirectional engine (shared input/output buffer).

◆ BR_SSL_BUFSIZE_OUTPUT

#define BR_SSL_BUFSIZE_OUTPUT (16384 + 85)

Optimal output buffer size.

◆ BR_SSL_CLOSED

#define BR_SSL_CLOSED 0x0001

SSL engine state: closed or failed.

◆ BR_SSL_RECVAPP

#define BR_SSL_RECVAPP 0x0010

SSL engine state: engine has received application data.

◆ BR_SSL_RECVREC

#define BR_SSL_RECVREC 0x0004

SSL engine state: engine may receive records from the peer.

◆ BR_SSL_SENDAPP

#define BR_SSL_SENDAPP 0x0008

SSL engine state: engine may accept application data to send.

◆ BR_SSL_SENDREC

#define BR_SSL_SENDREC 0x0002

SSL engine state: record data is ready to be sent to the peer.

◆ BR_TLS10

#define BR_TLS10 0x0301

Protocol version: TLS 1.0.

◆ BR_TLS11

#define BR_TLS11 0x0302

Protocol version: TLS 1.1.

◆ BR_TLS12

#define BR_TLS12 0x0303

Protocol version: TLS 1.2.

◆ BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 0x001B

◆ BR_TLS_DH_anon_WITH_AES_128_CBC_SHA

#define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA 0x0034

◆ BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256

#define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256 0x006C

◆ BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256

#define BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256 0x00A6

◆ BR_TLS_DH_anon_WITH_AES_256_CBC_SHA

#define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA 0x003A

◆ BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256

#define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256 0x006D

◆ BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384

#define BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384 0x00A7

◆ BR_TLS_DH_anon_WITH_RC4_128_MD5

#define BR_TLS_DH_anon_WITH_RC4_128_MD5 0x0018

◆ BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 0x000D

◆ BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA

#define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA 0x0030

◆ BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256

#define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256 0x003E

◆ BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256

#define BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256 0x00A4

◆ BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA

#define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA 0x0036

◆ BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256

#define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256 0x0068

◆ BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384

#define BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384 0x00A5

◆ BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 0x0010

◆ BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA 0x0031

◆ BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256 0x003F

◆ BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256 0x00A0

◆ BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA 0x0037

◆ BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256

#define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256 0x0069

◆ BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384 0x00A1

◆ BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 0x0013

◆ BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA

#define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA 0x0032

◆ BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256

#define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 0x0040

◆ BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256

#define BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 0x00A2

◆ BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA

#define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA 0x0038

◆ BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256

#define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 0x006A

◆ BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384

#define BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 0x00A3

◆ BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAD

◆ BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 0x0016

◆ BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA 0x0033

◆ BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 0x0067

◆ BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 0x009E

◆ BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x0039

◆ BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256

#define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 0x006B

◆ BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 0x009F

◆ BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCAA

◆ BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 0xC017

◆ BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA 0xC018

◆ BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA 0xC019

◆ BR_TLS_ECDH_anon_WITH_NULL_SHA

#define BR_TLS_ECDH_anon_WITH_NULL_SHA 0xC015

◆ BR_TLS_ECDH_anon_WITH_RC4_128_SHA

#define BR_TLS_ECDH_anon_WITH_RC4_128_SHA 0xC016

◆ BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC003

◆ BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0xC004

◆ BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC025

◆ BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 0xC02D

◆ BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0xC005

◆ BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384

#define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0xC026

◆ BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 0xC02E

◆ BR_TLS_ECDH_ECDSA_WITH_NULL_SHA

#define BR_TLS_ECDH_ECDSA_WITH_NULL_SHA 0xC001

◆ BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA

#define BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0xC002

◆ BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0xC00D

◆ BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0xC00E

◆ BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0xC029

◆ BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 0xC031

◆ BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0xC00F

◆ BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384

#define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0xC02A

◆ BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 0xC032

◆ BR_TLS_ECDH_RSA_WITH_NULL_SHA

#define BR_TLS_ECDH_RSA_WITH_NULL_SHA 0xC00B

◆ BR_TLS_ECDH_RSA_WITH_RC4_128_SHA

#define BR_TLS_ECDH_RSA_WITH_RC4_128_SHA 0xC00C

◆ BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC008

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0xC009

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM 0xC0AC

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 0xC0AE

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0xC00A

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM 0xC0AD

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8 0xC0AF

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C

◆ BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9

◆ BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA 0xC006

◆ BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0xC007

◆ BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAC

◆ BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0xC012

◆ BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0xC013

◆ BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0xC027

◆ BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC02F

◆ BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC014

◆ BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

#define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC028

◆ BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xC030

◆ BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8

◆ BR_TLS_ECDHE_RSA_WITH_NULL_SHA

#define BR_TLS_ECDHE_RSA_WITH_NULL_SHA 0xC010

◆ BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA

#define BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA 0xC011

◆ BR_TLS_FALLBACK_SCSV

#define BR_TLS_FALLBACK_SCSV 0x5600

◆ BR_TLS_NULL_WITH_NULL_NULL

#define BR_TLS_NULL_WITH_NULL_NULL 0x0000

◆ BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAB

◆ BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAE

◆ BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA 0x000A

◆ BR_TLS_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_RSA_WITH_AES_128_CBC_SHA 0x002F

◆ BR_TLS_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_RSA_WITH_AES_128_CBC_SHA256 0x003C

◆ BR_TLS_RSA_WITH_AES_128_CCM

#define BR_TLS_RSA_WITH_AES_128_CCM 0xC09C

◆ BR_TLS_RSA_WITH_AES_128_CCM_8

#define BR_TLS_RSA_WITH_AES_128_CCM_8 0xC0A0

◆ BR_TLS_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_RSA_WITH_AES_128_GCM_SHA256 0x009C

◆ BR_TLS_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_RSA_WITH_AES_256_CBC_SHA 0x0035

◆ BR_TLS_RSA_WITH_AES_256_CBC_SHA256

#define BR_TLS_RSA_WITH_AES_256_CBC_SHA256 0x003D

◆ BR_TLS_RSA_WITH_AES_256_CCM

#define BR_TLS_RSA_WITH_AES_256_CCM 0xC09D

◆ BR_TLS_RSA_WITH_AES_256_CCM_8

#define BR_TLS_RSA_WITH_AES_256_CCM_8 0xC0A1

◆ BR_TLS_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_RSA_WITH_AES_256_GCM_SHA384 0x009D

◆ BR_TLS_RSA_WITH_NULL_MD5

#define BR_TLS_RSA_WITH_NULL_MD5 0x0001

◆ BR_TLS_RSA_WITH_NULL_SHA

#define BR_TLS_RSA_WITH_NULL_SHA 0x0002

◆ BR_TLS_RSA_WITH_NULL_SHA256

#define BR_TLS_RSA_WITH_NULL_SHA256 0x003B

◆ BR_TLS_RSA_WITH_RC4_128_MD5

#define BR_TLS_RSA_WITH_RC4_128_MD5 0x0004

◆ BR_TLS_RSA_WITH_RC4_128_SHA

#define BR_TLS_RSA_WITH_RC4_128_SHA 0x0005

Typedef Documentation

◆ br_suite_translated

typedef uint16_t br_suite_translated[2]

Type for a "translated cipher suite", as an array of two 16-bit integers.

The first element is the cipher suite identifier (as used on the wire). The second element is the concatenation of four 4-bit elements which characterise the cipher suite contents. In most to least significant order, these 4-bit elements are:

Bits 12 to 15: key exchange + server key type

val	symbolic constant	suite type	details
0	`BR_SSLKEYX_RSA`	RSA	RSA key exchange, key is RSA (encryption)
1	`BR_SSLKEYX_ECDHE_RSA`	ECDHE_RSA	ECDHE key exchange, key is RSA (signature)
2	`BR_SSLKEYX_ECDHE_ECDSA`	ECDHE_ECDSA	ECDHE key exchange, key is EC (signature)
3	`BR_SSLKEYX_ECDH_RSA`	ECDH_RSA	Key is EC (key exchange), cert signed with RSA
4	`BR_SSLKEYX_ECDH_ECDSA`	ECDH_ECDSA	Key is EC (key exchange), cert signed with ECDSA

Bits 8 to 11: symmetric encryption algorithm

val	symbolic constant	symmetric encryption	key strength (bits)
0	`BR_SSLENC_3DES_CBC`	3DES/CBC	168
1	`BR_SSLENC_AES128_CBC`	AES-128/CBC	128
2	`BR_SSLENC_AES256_CBC`	AES-256/CBC	256
3	`BR_SSLENC_AES128_GCM`	AES-128/GCM	128
4	`BR_SSLENC_AES256_GCM`	AES-256/GCM	256
5	`BR_SSLENC_CHACHA20`	ChaCha20/Poly1305	256

Bits 4 to 7: MAC algorithm

val	symbolic constant	MAC type	details
0	`BR_SSLMAC_AEAD`	AEAD	No dedicated MAC (encryption is AEAD)
2	`BR_SSLMAC_SHA1`	HMAC/SHA-1	Value matches `br_sha1_ID`
4	`BR_SSLMAC_SHA256`	HMAC/SHA-256	Value matches `br_sha256_ID`
5	`BR_SSLMAC_SHA384`	HMAC/SHA-384	Value matches `br_sha384_ID`

Bits 0 to 3: hash function for PRF when used with TLS-1.2

val	symbolic constant	hash function	details
4	`BR_SSLPRF_SHA256`	SHA-256	Value matches `br_sha256_ID`
5	`BR_SSLPRF_SHA384`	SHA-384	Value matches `br_sha384_ID`

For instance, cipher suite TLS_RSA_WITH_AES_128_GCM_SHA256 has standard identifier 0x009C, and is translated to 0x0304, for, in that order: RSA key exchange (0), AES-128/GCM (3), AEAD integrity (0), SHA-256 in the TLS PRF (4).

Function Documentation

◆ br_ssl_client_forget_session()

static void br_ssl_client_forget_session ( br_ssl_client_context * cc )

inlinestatic

Forget any session in the context.

This means that the next handshake that uses this context will necessarily be a full handshake (this applies both to new connections and to renegotiations).

Parameters

cc	client context.

◆ br_ssl_client_get_server_curve()

static int br_ssl_client_get_server_curve ( const br_ssl_client_context * cc )

inlinestatic

Get the server key curve.

This function returns the ID for the curve used by the server's public key. This is set when the server's certificate chain is processed; this value is 0 if the server's key is not an EC key.

Returns: the server's public key curve ID, or 0.

◆ br_ssl_client_get_server_hashes()

static uint32_t br_ssl_client_get_server_hashes ( const br_ssl_client_context * cc )

inlinestatic

Get the hash functions and signature algorithms supported by the server.

This value is a bit field:

If RSA (PKCS#1 v1.5) is supported with hash function of ID x, then bit x is set (hash function ID is 0 for the special MD5+SHA-1, or 2 to 6 for the SHA family).
If ECDSA is supported with hash function of ID x, then bit 8+x is set.
Newer algorithms are symbolic 16-bit identifiers that do not represent signature algorithm and hash function separately. If the TLS-level identifier is 0x0800+x for a x in the 0..15 range, then bit 16+x is set.

"New algorithms" are currently defined only in draft documents, so this support is subject to possible change. Right now (early 2017), this maps ed25519 (EdDSA on Curve25519) to bit 23, and ed448 (EdDSA on Curve448) to bit 24. If the identifiers on the wire change in future document, then the decoding mechanism in BearSSL will be amended to keep mapping ed25519 and ed448 on bits 23 and 24, respectively. Mapping of other new algorithms (e.g. RSA/PSS) is not guaranteed yet.

Parameters

cc	client context.

Returns: the server-supported hash functions and signature algorithms.

◆ br_ssl_client_init_full()

void br_ssl_client_init_full	(	br_ssl_client_context *	cc,
		br_x509_minimal_context *	xc,
		const br_x509_trust_anchor *	trust_anchors,
		size_t	trust_anchors_num
	)

SSL client profile: full.

This function initialises the provided SSL client context with all supported algorithms and cipher suites. It also initialises a companion X.509 validation engine with all supported algorithms, and the provided trust anchors; the X.509 engine will be used by the client context to validate the server's certificate.

Parameters

cc	client context to initialise.
xc	X.509 validation context to initialise.
trust_anchors	trust anchors to use.
trust_anchors_num	number of trust anchors.

◆ br_ssl_client_reset()

int br_ssl_client_reset	(	br_ssl_client_context *	cc,
		const char *	server_name,
		int	resume_session
	)

Prepare or reset a client context for a new connection.

The server_name parameter is used to fill the SNI extension; the X.509 "minimal" engine will also match that name against the server names included in the server's certificate. If the parameter is NULL then no SNI extension will be sent, and the X.509 "minimal" engine (if used for server certificate validation) will not check presence of any specific name in the received certificate.

Therefore, setting the server_name to NULL shall be reserved to cases where alternate or additional methods are used to ascertain that the right server public key is used (e.g. a "known key" model).

If resume_session is non-zero and the context was previously used then the session parameters may be reused (depending on whether the server previously sent a non-empty session ID, and accepts the session resumption). The session parameters for session resumption can also be set explicitly with br_ssl_engine_set_session_parameters().

On failure, the context is marked as failed, and this function returns 0. A possible failure condition is when no initial entropy was injected, and none could be obtained from the OS (either OS randomness gathering is not supported, or it failed).

Parameters

cc	client context.
server_name	target server name, or `NULL`.
resume_session	non-zero to try session resumption.

Returns: 0 on failure, 1 on success.

◆ br_ssl_client_set_client_certificate()

static void br_ssl_client_set_client_certificate	(	br_ssl_client_context *	cc,
		const br_ssl_client_certificate_class **	pctx
	)

inlinestatic

Set an externally provided client certificate handler context.

The handler's methods are invoked when the server requests a client certificate.

Parameters

cc	client context.
pctx	certificate handler context (pointer to its vtable field).

◆ br_ssl_client_set_default_rsapub()

void br_ssl_client_set_default_rsapub ( br_ssl_client_context * cc )

Set the "default" RSA implementation for public-key operations.

This sets the RSA implementation in the client context (for encrypting the pre-master secret, in TLS_RSA_* cipher suites) to the fastest available on the current platform.

Parameters

cc	client context.

◆ br_ssl_client_set_min_clienthello_len()

static void br_ssl_client_set_min_clienthello_len	(	br_ssl_client_context *	cc,
		uint16_t	len
	)

inlinestatic

Set the minimum ClientHello length (RFC 7685 padding).

If this value is set and the ClientHello would be shorter, then the Pad ClientHello extension will be added with enough padding bytes to reach the target size. Because of the extension header, the resulting size will sometimes be slightly more than len bytes if the target size cannot be exactly met.

The target length relates to the contents of the ClientHello, not counting its 4-byte header. For instance, if len is set to 512, then the padding will bring the ClientHello size to 516 bytes with its header, and 521 bytes when counting the 5-byte record header.

Parameters

cc	client context.
len	minimum ClientHello length (in bytes).

◆ br_ssl_client_set_rsapub()

static void br_ssl_client_set_rsapub	(	br_ssl_client_context *	cc,
		br_rsa_public	irsapub
	)

inlinestatic

Set the RSA public-key operations implementation.

This will be used to encrypt the pre-master secret with the server's RSA public key (RSA-encryption cipher suites only).

Parameters

cc	client context.
irsapub	RSA public-key encryption implementation.

◆ br_ssl_client_set_single_ec()

void br_ssl_client_set_single_ec	(	br_ssl_client_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_ec_private_key *	sk,
		unsigned	allowed_usages,
		unsigned	cert_issuer_key_type,
		const br_ec_impl *	iec,
		br_ecdsa_sign	iecdsa
	)

◆ br_ssl_client_set_single_rsa()

void br_ssl_client_set_single_rsa	(	br_ssl_client_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_rsa_private_key *	sk,
		br_rsa_pkcs1_sign	irsasign
	)

Set client certificate chain and key (single RSA case).

This function sets a client certificate chain, that the client will send to the server whenever a client certificate is requested. This certificate uses an RSA public key; the corresponding private key is invoked for authentication. Trust anchor names sent by the server are ignored.

The provided chain and private key are linked in the client context; they must remain valid as long as they may be used, i.e. normally for the duration of the connection, since they might be invoked again upon renegotiations.

Parameters

cc	SSL client context.
chain	client certificate chain (SSL order: EE comes first).
chain_len	client chain length (number of certificates).
sk	client private key.
irsasign	RSA signature implementation (PKCS#1 v1.5).

◆ br_ssl_client_zero()

void br_ssl_client_zero ( br_ssl_client_context * cc )

Clear the complete contents of a SSL client context.

Everything is cleared, including the reference to the configured buffer, implementations, cipher suites and state. This is a preparatory step to assembling a custom profile.

Parameters

cc	client context to clear.

◆ br_ssl_engine_add_flags()

static void br_ssl_engine_add_flags	(	br_ssl_engine_context *	cc,
		uint32_t	flags
	)

inlinestatic

Set some engine behavioural flags.

The flags set in the flags parameter are set in the context; other flags are untouched.

Parameters

cc	SSL engine context.
flags	additional set flags.

◆ br_ssl_engine_close()

void br_ssl_engine_close ( br_ssl_engine_context * cc )

Initiate a closure.

If, at that point, the context is open and in ready state, then a close_notify alert is assembled and marked for sending; this triggers the closure protocol. Otherwise, no such alert is assembled.

Parameters

cc	SSL engine context.

◆ br_ssl_engine_current_state()

unsigned br_ssl_engine_current_state ( const br_ssl_engine_context * cc )

Get the current engine state.

An SSL engine (client or server) has, at any time, a state which is the combination of zero, one or more of these flags:

BR_SSL_CLOSED

Engine is finished, no more I/O (until next reset).
BR_SSL_SENDREC

Engine has some bytes to send to the peer.
BR_SSL_RECVREC

Engine expects some bytes from the peer.
BR_SSL_SENDAPP

Engine may receive application data to send (or flush).
BR_SSL_RECVAPP

Engine has obtained some application data from the peer, that should be read by the caller.

If no flag at all is set (state value is 0), then the engine is not fully initialised yet.

The BR_SSL_CLOSED flag is exclusive; when it is set, no other flag is set. To distinguish between a normal closure and an error, use br_ssl_engine_last_error().

Generally speaking, BR_SSL_SENDREC and BR_SSL_SENDAPP are mutually exclusive: the input buffer, at any point, either accumulates plaintext data, or contains an assembled record that is being sent. Similarly, BR_SSL_RECVREC and BR_SSL_RECVAPP are mutually exclusive. This may change in a future library version.

Parameters

cc	SSL engine context.

Returns: the current engine state.

◆ br_ssl_engine_flush()

void br_ssl_engine_flush	(	br_ssl_engine_context *	cc,
		int	force
	)

Flush buffered application data.

If some application data has been buffered in the engine, then wrap it into a record and mark it for sending. If no application data has been buffered but the engine would be ready to accept some, AND the force parameter is non-zero, then an empty record is assembled and marked for sending. In all other cases, this function does nothing.

Empty records are technically legal, but not all existing SSL/TLS implementations support them. Empty records can be useful as a transparent "keep-alive" mechanism to maintain some low-level network activity.

Parameters

cc	SSL engine context.
force	non-zero to force sending an empty record.

◆ br_ssl_engine_get_ec()

static const br_ec_impl* br_ssl_engine_get_ec ( br_ssl_engine_context * cc )

inlinestatic

Get the EC implementation configured in the provided engine.

Parameters

cc	SSL engine context.

Returns: the EC implementation.

◆ br_ssl_engine_get_ecdhe_curve()

static int br_ssl_engine_get_ecdhe_curve ( br_ssl_engine_context * cc )

inlinestatic

Get identifier for the curve used for key exchange.

If the cipher suite uses ECDHE, then this function returns the identifier for the curve used for transient parameters. This is defined during the course of the handshake, when the ServerKeyExchange is sent (on the server) or received (on the client). If the cipher suite does not use ECDHE (e.g. static ECDH, or RSA key exchange), then this value is indeterminate.

Parameters

cc	SSL engine context.

Returns: the ECDHE curve identifier.

◆ br_ssl_engine_get_ecdsa()

static br_ecdsa_vrfy br_ssl_engine_get_ecdsa ( br_ssl_engine_context * cc )

inlinestatic

Get the ECDSA implementation (signature verification) configured in the provided engine.

Parameters

cc	SSL engine context.

Returns: the ECDSA signature verification implementation.

◆ br_ssl_engine_get_flags()

static uint32_t br_ssl_engine_get_flags ( br_ssl_engine_context * cc )

inlinestatic

Get currently defined engine behavioural flags.

Parameters

cc	SSL engine context.

Returns: the flags.

◆ br_ssl_engine_get_hash()

static const br_hash_class* br_ssl_engine_get_hash	(	br_ssl_engine_context *	ctx,
		int	id
	)

inlinestatic

Get a hash function implementation (by ID).

This function retrieves a hash function implementation which was set with br_ssl_engine_set_hash().

Parameters

ctx	SSL engine context.
id	hash function identifier.

Returns: the hash function implementation (or NULL).

◆ br_ssl_engine_get_rsavrfy()

static br_rsa_pkcs1_vrfy br_ssl_engine_get_rsavrfy ( br_ssl_engine_context * cc )

inlinestatic

Get the RSA implementation (signature verification) configured in the provided engine.

Parameters

cc	SSL engine context.

Returns: the RSA signature verification implementation.

◆ br_ssl_engine_get_selected_protocol()

static const char* br_ssl_engine_get_selected_protocol ( br_ssl_engine_context * ctx )

inlinestatic

Get the selected protocol.

If this context was initialised with a non-empty list of protocol names, and both client and server sent ALPN extensions during the handshake, and a common name was found, then that name is returned. Otherwise, NULL is returned.

The returned pointer is one of the pointers provided to the context with br_ssl_engine_set_protocol_names().

Returns: the selected protocol, or NULL.

◆ br_ssl_engine_get_server_name()

static const char* br_ssl_engine_get_server_name ( const br_ssl_engine_context * cc )

inlinestatic

Get the "server name" in this engine.

For clients, this is the name provided with br_ssl_client_reset(); for servers, this is the name received from the client as part of the ClientHello message. If there is no such name (e.g. the client did not send an SNI extension) then the returned string is empty (returned pointer points to a byte of value 0).

The returned pointer refers to a buffer inside the context, which may be overwritten as part of normal SSL activity (even within the same connection, if a renegotiation occurs).

Parameters

cc	SSL engine context.

Returns: the server name (possibly empty).

◆ br_ssl_engine_get_session_parameters()

static void br_ssl_engine_get_session_parameters	(	const br_ssl_engine_context *	cc,
		br_ssl_session_parameters *	pp
	)

inlinestatic

Get a copy of the session parameters.

The session parameters are filled during the handshake, so this function shall not be called before completion of the handshake. The initial handshake is completed when the context first allows application data to be injected.

This function copies the current session parameters into the provided structure. Beware that the session parameters include the master secret, which is sensitive data, to handle with great care.

Parameters

cc	SSL engine context.
pp	destination structure for the session parameters.

◆ br_ssl_engine_get_version()

static unsigned br_ssl_engine_get_version ( const br_ssl_engine_context * cc )

inlinestatic

Get the protocol version.

This function returns the protocol version that is used by the engine. That value is set after sending (for a server) or receiving (for a client) the ServerHello message.

Parameters

cc	SSL engine context.

Returns: the protocol version.

◆ br_ssl_engine_inject_entropy()

void br_ssl_engine_inject_entropy	(	br_ssl_engine_context *	cc,
		const void *	data,
		size_t	len
	)

Inject some "initial entropy" in the context.

This entropy will be added to what can be obtained from the underlying operating system, if that OS is supported.

This function may be called several times; all injected entropy chunks are cumulatively mixed.

If entropy gathering from the OS is supported and compiled in, then this step is optional. Otherwise, it is mandatory to inject randomness, and the caller MUST take care to push (as one or several successive calls) enough entropy to achieve cryptographic resistance (at least 80 bits, preferably 128 or more). The engine will report an error if no entropy was provided and none can be obtained from the OS.

Take care that this function cannot assess the cryptographic quality of the provided bytes.

In all generality, "entropy" must here be considered to mean "that which the attacker cannot predict". If your OS/architecture does not have a suitable source of randomness, then you can make do with the combination of a large enough secret value (possibly a copy of an asymmetric private key that you also store on the system) AND a non-repeating value (e.g. current time, provided that the local clock cannot be reset or altered by the attacker).

Parameters

cc	SSL engine context.
data	extra entropy to inject.
len	length of the extra data (in bytes).

◆ br_ssl_engine_last_error()

static int br_ssl_engine_last_error ( const br_ssl_engine_context * cc )

inlinestatic

Get the engine error indicator.

The error indicator is BR_ERR_OK (0) if no error was encountered since the last call to br_ssl_client_reset() or br_ssl_server_reset(). Other status values are "sticky": they remain set, and prevent all I/O activity, until cleared. Only the reset calls clear the error indicator.

Parameters

cc	SSL engine context.

Returns: 0, or a non-zero error code.

◆ br_ssl_engine_recvapp_ack()

void br_ssl_engine_recvapp_ack	(	br_ssl_engine_context *	cc,
		size_t	len
	)

Acknowledge some received application data.

After reading len bytes from the buffer returned by br_ssl_engine_recvapp_buf(), the application shall call this function to trigger any relevant processing. The len parameter MUST NOT be 0, and MUST NOT exceed the value obtained in the br_ssl_engine_recvapp_buf() call.

Parameters

cc	SSL engine context.
len	number of bytes read (not zero).

◆ br_ssl_engine_recvapp_buf()

unsigned char* br_ssl_engine_recvapp_buf	(	const br_ssl_engine_context *	cc,
		size_t *	len
	)

Get buffer for received application data.

If the engine has received application data from the peer, hen this call returns a pointer to the buffer from where such data shall be read, and its length is written in *len. Otherwise, *len is set to 0 and NULL is returned.

Parameters

cc	SSL engine context.
len	receives the application data input buffer length, or 0.

Returns: the application data input buffer, or NULL.

◆ br_ssl_engine_recvrec_ack()

void br_ssl_engine_recvrec_ack	(	br_ssl_engine_context *	cc,
		size_t	len
	)

Inform the engine of some new record data.

After writing len bytes in the buffer returned by br_ssl_engine_recvrec_buf(), the application shall call this function to trigger any relevant processing. The len parameter MUST NOT be 0, and MUST NOT exceed the value obtained in the br_ssl_engine_recvrec_buf() call.

Parameters

cc	SSL engine context.
len	number of bytes pushed (not zero).

◆ br_ssl_engine_recvrec_buf()

unsigned char* br_ssl_engine_recvrec_buf	(	const br_ssl_engine_context *	cc,
		size_t *	len
	)

Get buffer for incoming records.

If the engine is ready to accept records from the peer, then this call returns a pointer to the buffer where such data shall be written, and its length is written in *len. Otherwise, *len is set to 0 and NULL is returned.

Parameters

cc	SSL engine context.
len	receives the record data input buffer length, or 0.

Returns: the record data input buffer, or NULL.

◆ br_ssl_engine_remove_flags()

static void br_ssl_engine_remove_flags	(	br_ssl_engine_context *	cc,
		uint32_t	flags
	)

inlinestatic

Clear some engine behavioural flags.

The flags set in the flags parameter are cleared from the context; other flags are untouched.

Parameters

cc	SSL engine context.
flags	flags to remove.

◆ br_ssl_engine_renegotiate()

int br_ssl_engine_renegotiate ( br_ssl_engine_context * cc )

Initiate a renegotiation.

If the engine is failed or closed, or if the peer is known not to support secure renegotiation (RFC 5746), or if renegotiations have been disabled with the BR_OPT_NO_RENEGOTIATION flag, or if there is buffered incoming application data, then this function returns 0 and nothing else happens.

Otherwise, this function returns 1, and a renegotiation attempt is triggered (if a handshake is already ongoing at that point, then no new handshake is triggered).

Parameters

cc	SSL engine context.

Returns: 1 on success, 0 on error.

◆ br_ssl_engine_sendapp_ack()

void br_ssl_engine_sendapp_ack	(	br_ssl_engine_context *	cc,
		size_t	len
	)

Inform the engine of some new application data.

After writing len bytes in the buffer returned by br_ssl_engine_sendapp_buf(), the application shall call this function to trigger any relevant processing. The len parameter MUST NOT be 0, and MUST NOT exceed the value obtained in the br_ssl_engine_sendapp_buf() call.

Parameters

cc	SSL engine context.
len	number of bytes pushed (not zero).

◆ br_ssl_engine_sendapp_buf()

unsigned char* br_ssl_engine_sendapp_buf	(	const br_ssl_engine_context *	cc,
		size_t *	len
	)

Get buffer for application data to send.

If the engine is ready to accept application data to send to the peer, then this call returns a pointer to the buffer where such data shall be written, and its length is written in *len. Otherwise, *len is set to 0 and NULL is returned.

Parameters

cc	SSL engine context.
len	receives the application data output buffer length, or 0.

Returns: the application data output buffer, or NULL.

◆ br_ssl_engine_sendrec_ack()

void br_ssl_engine_sendrec_ack	(	br_ssl_engine_context *	cc,
		size_t	len
	)

Acknowledge some sent record data.

After reading len bytes from the buffer returned by br_ssl_engine_sendrec_buf(), the application shall call this function to trigger any relevant processing. The len parameter MUST NOT be 0, and MUST NOT exceed the value obtained in the br_ssl_engine_sendrec_buf() call.

Parameters

cc	SSL engine context.
len	number of bytes read (not zero).

◆ br_ssl_engine_sendrec_buf()

unsigned char* br_ssl_engine_sendrec_buf	(	const br_ssl_engine_context *	cc,
		size_t *	len
	)

Get buffer for record data to send.

If the engine has prepared some records to send to the peer, then this call returns a pointer to the buffer from where such data shall be read, and its length is written in *len. Otherwise, *len is set to 0 and NULL is returned.

Parameters

cc	SSL engine context.
len	receives the record data output buffer length, or 0.

Returns: the record data output buffer, or NULL.

◆ br_ssl_engine_set_aes_cbc()

static void br_ssl_engine_set_aes_cbc	(	br_ssl_engine_context *	cc,
		const br_block_cbcenc_class *	impl_enc,
		const br_block_cbcdec_class *	impl_dec
	)

inlinestatic

Set the AES/CBC implementations.

Parameters

cc	SSL engine context.
impl_enc	AES/CBC encryption implementation (or `NULL`).
impl_dec	AES/CBC decryption implementation (or `NULL`).

◆ br_ssl_engine_set_aes_ctr()

static void br_ssl_engine_set_aes_ctr	(	br_ssl_engine_context *	cc,
		const br_block_ctr_class *	impl
	)

inlinestatic

Set the AES/CTR implementation.

Parameters

cc	SSL engine context.
impl	AES/CTR encryption/decryption implementation (or `NULL`).

◆ br_ssl_engine_set_aes_ctrcbc()

static void br_ssl_engine_set_aes_ctrcbc	(	br_ssl_engine_context *	cc,
		const br_block_ctrcbc_class *	impl
	)

inlinestatic

Set the AES/CTR+CBC implementation.

Parameters

cc	SSL engine context.
impl	AES/CTR+CBC encryption/decryption implementation (or `NULL`).

◆ br_ssl_engine_set_all_flags()

static void br_ssl_engine_set_all_flags	(	br_ssl_engine_context *	cc,
		uint32_t	flags
	)

inlinestatic

Set all engine behavioural flags.

Parameters

cc	SSL engine context.
flags	new value for all flags.

◆ br_ssl_engine_set_buffer()

void br_ssl_engine_set_buffer	(	br_ssl_engine_context *	cc,
		void *	iobuf,
		size_t	iobuf_len,
		int	bidi
	)

Set the I/O buffer for the SSL engine.

Once this call has been made, br_ssl_client_reset() or br_ssl_server_reset() MUST be called before using the context.

The provided buffer will be used as long as the engine context is used. The caller is responsible for keeping it available.

If bidi is 0, then the engine will operate in half-duplex mode (it won't be able to send data while there is unprocessed incoming data in the buffer, and it won't be able to receive data while there is unsent data in the buffer). The optimal buffer size in half-duplex mode is BR_SSL_BUFSIZE_MONO; if the buffer is larger, then extra bytes are ignored. If the buffer is smaller, then this limits the capacity of the engine to support all allowed record sizes.

If bidi is 1, then the engine will split the buffer into two parts, for separate handling of outgoing and incoming data. This enables full-duplex processing, but requires more RAM. The optimal buffer size in full-duplex mode is BR_SSL_BUFSIZE_BIDI; if the buffer is larger, then extra bytes are ignored. If the buffer is smaller, then the split will favour the incoming part, so that interoperability is maximised.

Parameters

cc	SSL engine context
iobuf	I/O buffer.
iobuf_len	I/O buffer length (in bytes).
bidi	non-zero for full-duplex mode.

◆ br_ssl_engine_set_buffers_bidi()

void br_ssl_engine_set_buffers_bidi	(	br_ssl_engine_context *	cc,
		void *	ibuf,
		size_t	ibuf_len,
		void *	obuf,
		size_t	obuf_len
	)

Set the I/O buffers for the SSL engine.

Once this call has been made, br_ssl_client_reset() or br_ssl_server_reset() MUST be called before using the context.

This function is similar to br_ssl_engine_set_buffer(), except that it enforces full-duplex mode, and the two I/O buffers are provided as separate chunks.

The macros BR_SSL_BUFSIZE_INPUT and BR_SSL_BUFSIZE_OUTPUT evaluate to the optimal (maximum) sizes for the input and output buffer, respectively.

Parameters

cc	SSL engine context
ibuf	input buffer.
ibuf_len	input buffer length (in bytes).
obuf	output buffer.
obuf_len	output buffer length (in bytes).

◆ br_ssl_engine_set_cbc()

static void br_ssl_engine_set_cbc	(	br_ssl_engine_context *	cc,
		const br_sslrec_in_cbc_class *	impl_in,
		const br_sslrec_out_cbc_class *	impl_out
	)

inlinestatic

Set the record encryption and decryption engines for CBC + HMAC.

Parameters

cc	SSL engine context.
impl_in	record CBC decryption implementation (or `NULL`).
impl_out	record CBC encryption implementation (or `NULL`).

◆ br_ssl_engine_set_ccm()

static void br_ssl_engine_set_ccm	(	br_ssl_engine_context *	cc,
		const br_sslrec_in_ccm_class *	impl_in,
		const br_sslrec_out_ccm_class *	impl_out
	)

inlinestatic

Set the record encryption and decryption engines for CCM.

Parameters

cc	SSL engine context.
impl_in	record CCM decryption implementation (or `NULL`).
impl_out	record CCM encryption implementation (or `NULL`).

◆ br_ssl_engine_set_chacha20()

static void br_ssl_engine_set_chacha20	(	br_ssl_engine_context *	cc,
		br_chacha20_run	ichacha
	)

inlinestatic

Set the ChaCha20 implementation.

Parameters

cc	SSL engine context.
ichacha	ChaCha20 implementation (or `NULL`).

◆ br_ssl_engine_set_chapol()

static void br_ssl_engine_set_chapol	(	br_ssl_engine_context *	cc,
		const br_sslrec_in_chapol_class *	impl_in,
		const br_sslrec_out_chapol_class *	impl_out
	)

inlinestatic

Set the record encryption and decryption engines for ChaCha20+Poly1305.

Parameters

cc	SSL engine context.
impl_in	record ChaCha20 decryption implementation (or `NULL`).
impl_out	record ChaCha20 encryption implementation (or `NULL`).

◆ br_ssl_engine_set_default_aes_cbc()

void br_ssl_engine_set_default_aes_cbc ( br_ssl_engine_context * cc )

Set the "default" AES/CBC implementations.

This function configures in the engine the AES implementations that should provide best runtime performance on the local system, while still being safe (in particular, constant-time). It also sets the handlers for CBC records.

Parameters

cc	SSL engine context.

◆ br_ssl_engine_set_default_aes_ccm()

void br_ssl_engine_set_default_aes_ccm ( br_ssl_engine_context * cc )

Set the "default" implementations for AES/CCM.

This function configures in the engine the AES/CTR+CBC implementation that should provide best runtime performance on the local system, while still being safe (in particular, constant-time). It also sets the handlers for CCM records.

Parameters

cc	SSL engine context.

◆ br_ssl_engine_set_default_aes_gcm()

void br_ssl_engine_set_default_aes_gcm ( br_ssl_engine_context * cc )

Set the "default" implementations for AES/GCM (AES/CTR + GHASH).

This function configures in the engine the AES/CTR and GHASH implementation that should provide best runtime performance on the local system, while still being safe (in particular, constant-time). It also sets the handlers for GCM records.

Parameters

cc	SSL engine context.

◆ br_ssl_engine_set_default_chapol()

void br_ssl_engine_set_default_chapol ( br_ssl_engine_context * cc )

Set the "default" ChaCha20 and Poly1305 implementations.

This function configures in the engine the ChaCha20 and Poly1305 implementations that should provide best runtime performance on the local system, while still being safe (in particular, constant-time). It also sets the handlers for ChaCha20+Poly1305 records.

Parameters

cc	SSL engine context.

◆ br_ssl_engine_set_default_des_cbc()

void br_ssl_engine_set_default_des_cbc ( br_ssl_engine_context * cc )

Set the "default" DES/CBC implementations.

This function configures in the engine the DES implementations that should provide best runtime performance on the local system, while still being safe (in particular, constant-time). It also sets the handlers for CBC records.

Parameters

cc	SSL engine context.

◆ br_ssl_engine_set_default_ec()

void br_ssl_engine_set_default_ec ( br_ssl_engine_context * cc )

Set the "default" EC implementation.

This function sets the elliptic curve implementation for ECDH and ECDHE cipher suites, and for ECDSA support. It selects the fastest implementation on the current system.

Parameters

cc	SSL engine context.

◆ br_ssl_engine_set_default_ecdsa()

void br_ssl_engine_set_default_ecdsa ( br_ssl_engine_context * cc )

Set the "default" ECDSA implementation (signature verification).

This function sets the ECDSA implementation (signature verification) to the fastest implementation available on the current platform. This call also sets the elliptic curve implementation itself, there again to the fastest EC implementation available.

Parameters

cc	SSL engine context.

◆ br_ssl_engine_set_default_rsavrfy()

void br_ssl_engine_set_default_rsavrfy ( br_ssl_engine_context * cc )

Set the "default" RSA implementation (signature verification).

This function sets the RSA implementation (signature verification) to the fastest implementation available on the current platform.

Parameters

cc	SSL engine context.

◆ br_ssl_engine_set_des_cbc()

static void br_ssl_engine_set_des_cbc	(	br_ssl_engine_context *	cc,
		const br_block_cbcenc_class *	impl_enc,
		const br_block_cbcdec_class *	impl_dec
	)

inlinestatic

Set the DES/CBC implementations.

Parameters

cc	SSL engine context.
impl_enc	DES/CBC encryption implementation (or `NULL`).
impl_dec	DES/CBC decryption implementation (or `NULL`).

◆ br_ssl_engine_set_ec()

static void br_ssl_engine_set_ec	(	br_ssl_engine_context *	cc,
		const br_ec_impl *	iec
	)

inlinestatic

Set the EC implementation.

The elliptic curve implementation will be used for ECDH and ECDHE cipher suites, and for ECDSA support.

Parameters

cc	SSL engine context.
iec	EC implementation (or `NULL`).

◆ br_ssl_engine_set_ecdsa()

static void br_ssl_engine_set_ecdsa	(	br_ssl_engine_context *	cc,
		br_ecdsa_vrfy	iecdsa
	)

inlinestatic

◆ br_ssl_engine_set_gcm()

static void br_ssl_engine_set_gcm	(	br_ssl_engine_context *	cc,
		const br_sslrec_in_gcm_class *	impl_in,
		const br_sslrec_out_gcm_class *	impl_out
	)

inlinestatic

Set the record encryption and decryption engines for GCM.

Parameters

cc	SSL engine context.
impl_in	record GCM decryption implementation (or `NULL`).
impl_out	record GCM encryption implementation (or `NULL`).

◆ br_ssl_engine_set_ghash()

static void br_ssl_engine_set_ghash	(	br_ssl_engine_context *	cc,
		br_ghash	impl
	)

inlinestatic

Set the GHASH implementation (used in GCM mode).

Parameters

cc	SSL engine context.
impl	GHASH implementation (or `NULL`).

◆ br_ssl_engine_set_hash()

static void br_ssl_engine_set_hash	(	br_ssl_engine_context *	ctx,
		int	id,
		const br_hash_class *	impl
	)

inlinestatic

Set a hash function implementation (by ID).

Hash functions set with this call will be used for SSL/TLS specific usages, not X.509 certificate validation. Only "standard" hash functions may be set (MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512). If impl is NULL, then the hash function support is removed, not added.

Parameters

ctx	SSL engine context.
id	hash function identifier.
impl	hash function implementation (or `NULL`).

◆ br_ssl_engine_set_poly1305()

static void br_ssl_engine_set_poly1305	(	br_ssl_engine_context *	cc,
		br_poly1305_run	ipoly
	)

inlinestatic

Set the Poly1305 implementation.

Parameters

cc	SSL engine context.
ipoly	Poly1305 implementation (or `NULL`).

◆ br_ssl_engine_set_prf10()

static void br_ssl_engine_set_prf10	(	br_ssl_engine_context *	cc,
		br_tls_prf_impl	impl
	)

inlinestatic

Set the PRF implementation (for TLS 1.0 and 1.1).

This function sets (or removes, if impl is NULL) the implementation for the PRF used in TLS 1.0 and 1.1.

Parameters

cc	SSL engine context.
impl	PRF implementation (or `NULL`).

◆ br_ssl_engine_set_prf_sha256()

static void br_ssl_engine_set_prf_sha256	(	br_ssl_engine_context *	cc,
		br_tls_prf_impl	impl
	)

inlinestatic

Set the PRF implementation with SHA-256 (for TLS 1.2).

This function sets (or removes, if impl is NULL) the implementation for the SHA-256 variant of the PRF used in TLS 1.2.

Parameters

cc	SSL engine context.
impl	PRF implementation (or `NULL`).

◆ br_ssl_engine_set_prf_sha384()

static void br_ssl_engine_set_prf_sha384	(	br_ssl_engine_context *	cc,
		br_tls_prf_impl	impl
	)

inlinestatic

Set the PRF implementation with SHA-384 (for TLS 1.2).

This function sets (or removes, if impl is NULL) the implementation for the SHA-384 variant of the PRF used in TLS 1.2.

Parameters

cc	SSL engine context.
impl	PRF implementation (or `NULL`).

◆ br_ssl_engine_set_protocol_names()

static void br_ssl_engine_set_protocol_names	(	br_ssl_engine_context *	ctx,
		const char **	names,
		size_t	num
	)

inlinestatic

Set the supported protocol names.

Protocol names are part of the ALPN extension (RFC 7301). Each protocol name is a character string, containing no more than 255 characters (256 with the terminating zero). When names are set, then:

The client will send an ALPN extension, containing the names. If the server responds with an ALPN extension, the client will verify that the response contains one of its name, and report that name through br_ssl_engine_get_selected_protocol().
The server will parse incoming ALPN extension (from clients), and try to find a common protocol; if none is found, the connection is aborted with a fatal alert. On match, a response ALPN extension is sent, and name is reported through br_ssl_engine_get_selected_protocol().

The provided array is linked in, and must remain valid while the connection is live.

Names MUST NOT be empty. Names MUST NOT be longer than 255 characters (excluding the terminating 0).

Parameters

ctx	SSL engine context.
names	list of protocol names (zero-terminated).
num	number of protocol names (MUST be 1 or more).

◆ br_ssl_engine_set_rsavrfy()

static void br_ssl_engine_set_rsavrfy	(	br_ssl_engine_context *	cc,
		br_rsa_pkcs1_vrfy	irsavrfy
	)

inlinestatic

Set the RSA signature verification implementation.

On the client, this is used to verify the server's signature on its ServerKeyExchange message (for ECDHE_RSA cipher suites). On the server, this is used to verify the client's CertificateVerify message (if a client certificate is requested, and that certificate contains a RSA key).

Parameters

cc	SSL engine context.
irsavrfy	RSA signature verification implementation.

◆ br_ssl_engine_set_session_parameters()

static void br_ssl_engine_set_session_parameters	(	br_ssl_engine_context *	cc,
		const br_ssl_session_parameters *	pp
	)

inlinestatic

Set the session parameters to the provided values.

This function is meant to be used in the client, before doing a new handshake; a session resumption will be attempted with these parameters. In the server, this function has no effect.

Parameters

cc	SSL engine context.
pp	source structure for the session parameters.

◆ br_ssl_engine_set_suites()

void br_ssl_engine_set_suites	(	br_ssl_engine_context *	cc,
		const uint16_t *	suites,
		size_t	suites_num
	)

Set the list of cipher suites advertised by this context.

The provided array is copied into the context. It is the caller responsibility to ensure that all provided suites will be supported by the context. The engine context has enough room to receive all suites supported by the implementation. The provided array MUST NOT contain duplicates.

If the engine is for a client, the "signaling" pseudo-cipher suite TLS_FALLBACK_SCSV can be added at the end of the list, if the calling application is performing a voluntary downgrade (voluntary downgrades are not recommended, but if such a downgrade is done, then adding the fallback pseudo-suite is a good idea).

Parameters

cc	SSL engine context.
suites	cipher suites.
suites_num	number of cipher suites.

◆ br_ssl_engine_set_versions()

static void br_ssl_engine_set_versions	(	br_ssl_engine_context *	cc,
		unsigned	version_min,
		unsigned	version_max
	)

inlinestatic

Set the minimum and maximum supported protocol versions.

The two provided versions MUST be supported by the implementation (i.e. TLS 1.0, 1.1 and 1.2), and version_max MUST NOT be lower than version_min.

Parameters

cc	SSL engine context.
version_min	minimum supported TLS version.
version_max	maximum supported TLS version.

◆ br_ssl_engine_set_x509()

static void br_ssl_engine_set_x509	(	br_ssl_engine_context *	cc,
		const br_x509_class **	x509ctx
	)

inlinestatic

Set the X.509 engine.

The caller shall ensure that the X.509 engine is properly initialised.

Parameters

cc	SSL engine context.
x509ctx	X.509 certificate validation context.

◆ br_ssl_key_export()

int br_ssl_key_export	(	br_ssl_engine_context *	cc,
		void *	dst,
		size_t	len,
		const char *	label,
		const void *	context,
		size_t	context_len
	)

Export key material from a connected SSL engine (RFC 5705).

This calls compute a secret key of arbitrary length from the master secret of a connected SSL engine. If the provided context is not currently in "application data" state (initial handshake is not finished, another handshake is ongoing, or the connection failed or was closed), then this function returns 0. Otherwise, a secret key of length len bytes is computed and written in the buffer pointed to by dst, and 1 is returned.

The computed key follows the specification described in RFC 5705. That RFC includes two key computations, with and without a "context value". If context is NULL, then the variant without context is used; otherwise, the context_len bytes located at the address pointed to by context are used in the computation. Note that it is possible to have a "with context" key with a context length of zero bytes, by setting context to a non-NULL value but context_len to 0.

When context bytes are used, the context length MUST NOT exceed 65535 bytes.

Parameters

cc	SSL engine context.
dst	destination buffer for exported key.
len	exported key length (in bytes).
label	disambiguation label.
context	context value (or `NULL`).
context_len	context length (in bytes).

Returns: 1 on success, 0 on error.

◆ br_ssl_server_get_client_curves()

static uint32_t br_ssl_server_get_client_curves ( const br_ssl_server_context * cc )

inlinestatic

Get the elliptic curves supported by the client.

This is a bit field (bit x is set if curve of ID x is supported).

Parameters

cc	server context.

Returns: the client-supported elliptic curves.

◆ br_ssl_server_get_client_hashes()

static uint32_t br_ssl_server_get_client_hashes ( const br_ssl_server_context * cc )

inlinestatic

Get the hash functions and signature algorithms supported by the client.

This value is a bit field:

If RSA (PKCS#1 v1.5) is supported with hash function of ID x, then bit x is set (hash function ID is 0 for the special MD5+SHA-1, or 2 to 6 for the SHA family).
If ECDSA is supported with hash function of ID x, then bit 8+x is set.
Newer algorithms are symbolic 16-bit identifiers that do not represent signature algorithm and hash function separately. If the TLS-level identifier is 0x0800+x for a x in the 0..15 range, then bit 16+x is set.

"New algorithms" are currently defined only in draft documents, so this support is subject to possible change. Right now (early 2017), this maps ed25519 (EdDSA on Curve25519) to bit 23, and ed448 (EdDSA on Curve448) to bit 24. If the identifiers on the wire change in future document, then the decoding mechanism in BearSSL will be amended to keep mapping ed25519 and ed448 on bits 23 and 24, respectively. Mapping of other new algorithms (e.g. RSA/PSS) is not guaranteed yet.

Parameters

cc	server context.

Returns: the client-supported hash functions and signature algorithms.

◆ br_ssl_server_get_client_suites()

static const br_suite_translated* br_ssl_server_get_client_suites	(	const br_ssl_server_context *	cc,
		size_t *	num
	)

inlinestatic

Get the supported client suites.

This function shall be called only after the ClientHello has been processed, typically from the policy engine. The returned array contains the cipher suites that are supported by both the client and the server; these suites are in client preference order, unless the BR_OPT_ENFORCE_SERVER_PREFERENCES flag was set, in which case they are in server preference order.

The suites are translated, which means that each suite is given as two 16-bit integers: the standard suite identifier, and its translated version, broken down into its individual components, as explained with the br_suite_translated type.

The returned array is allocated in the context and will be rewritten by each handshake.

Parameters

cc	server context.
num	receives the array size (number of suites).

Returns: the translated common cipher suites, in preference order.

◆ br_ssl_server_init_full_ec()

void br_ssl_server_init_full_ec	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		unsigned	cert_issuer_key_type,
		const br_ec_private_key *	sk
	)

SSL server profile: full_ec.

This function initialises the provided SSL server context with all supported algorithms and cipher suites that rely on an EC key pair.

The key type of the CA that issued the server's certificate must be provided, since it matters for ECDH cipher suites (ECDH_RSA suites require a RSA-powered CA). The key type is either BR_KEYTYPE_RSA or BR_KEYTYPE_EC.

Parameters

cc	server context to initialise.
chain	server certificate chain.
chain_len	chain length (number of certificates).
cert_issuer_key_type	certificate issuer's key type.
sk	EC private key.

◆ br_ssl_server_init_full_rsa()

void br_ssl_server_init_full_rsa	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_rsa_private_key *	sk
	)

SSL server profile: full_rsa.

This function initialises the provided SSL server context with all supported algorithms and cipher suites that rely on a RSA key pair.

Parameters

cc	server context to initialise.
chain	server certificate chain.
chain_len	certificate chain length (number of certificate).
sk	RSA private key.

◆ br_ssl_server_init_mine2c()

void br_ssl_server_init_mine2c	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_rsa_private_key *	sk
	)

SSL server profile: mine2c.

This profile uses only TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256. Server key is RSA, and ECDHE key exchange is used. This suite provides forward security.

Parameters

cc	server context to initialise.
chain	server certificate chain.
chain_len	certificate chain length (number of certificate).
sk	RSA private key.

◆ br_ssl_server_init_mine2g()

void br_ssl_server_init_mine2g	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_rsa_private_key *	sk
	)

SSL server profile: mine2g.

This profile uses only TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256. Server key is RSA, and ECDHE key exchange is used. This suite provides forward security, with a higher CPU expense on the client, and a somewhat larger code footprint (compared to "minr2g").

Parameters

cc	server context to initialise.
chain	server certificate chain.
chain_len	certificate chain length (number of certificate).
sk	RSA private key.

◆ br_ssl_server_init_minf2c()

void br_ssl_server_init_minf2c	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_ec_private_key *	sk
	)

SSL server profile: minf2c.

This profile uses only TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256. Server key is EC, and ECDHE key exchange is used. This suite provides forward security.

Parameters

cc	server context to initialise.
chain	server certificate chain.
chain_len	certificate chain length (number of certificate).
sk	EC private key.

◆ br_ssl_server_init_minf2g()

void br_ssl_server_init_minf2g	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_ec_private_key *	sk
	)

SSL server profile: minf2g.

This profile uses only TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256. Server key is EC, and ECDHE key exchange is used. This suite provides forward security, with a higher CPU expense on the client and server (by a factor of about 3 to 4), and a somewhat larger code footprint (compared to "minu2g" and "minv2g").

Parameters

cc	server context to initialise.
chain	server certificate chain.
chain_len	certificate chain length (number of certificate).
sk	EC private key.

◆ br_ssl_server_init_minr2g()

void br_ssl_server_init_minr2g	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_rsa_private_key *	sk
	)

SSL server profile: minr2g.

This profile uses only TLS_RSA_WITH_AES_128_GCM_SHA256. Server key is RSA, and RSA key exchange is used (not forward secure, but uses little CPU in the client).

Parameters

cc	server context to initialise.
chain	server certificate chain.
chain_len	certificate chain length (number of certificate).
sk	RSA private key.

◆ br_ssl_server_init_minu2g()

void br_ssl_server_init_minu2g	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_ec_private_key *	sk
	)

SSL server profile: minu2g.

This profile uses only TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256. Server key is EC, and ECDH key exchange is used; the issuing CA used a RSA key.

The "minu2g" and "minv2g" profiles do not provide forward secrecy, but are the lightest on the server (for CPU usage), and are rather inexpensive on the client as well.

Parameters

cc	server context to initialise.
chain	server certificate chain.
chain_len	certificate chain length (number of certificate).
sk	EC private key.

◆ br_ssl_server_init_minv2g()

void br_ssl_server_init_minv2g	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_ec_private_key *	sk
	)

SSL server profile: minv2g.

This profile uses only TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256. Server key is EC, and ECDH key exchange is used; the issuing CA used an EC key.

The "minu2g" and "minv2g" profiles do not provide forward secrecy, but are the lightest on the server (for CPU usage), and are rather inexpensive on the client as well.

Parameters

cc	server context to initialise.
chain	server certificate chain.
chain_len	certificate chain length (number of certificate).
sk	EC private key.

◆ br_ssl_server_reset()

int br_ssl_server_reset ( br_ssl_server_context * cc )

Prepare or reset a server context for handling an incoming client.

Parameters

cc	server context.

Returns: 1 on success, 0 on error.

◆ br_ssl_server_set_cache()

static void br_ssl_server_set_cache	(	br_ssl_server_context *	cc,
		const br_ssl_session_cache_class **	vtable
	)

inlinestatic

Configure the cache for session parameters.

The cache context is provided as a pointer to its first field (vtable pointer).

Parameters

cc	server context.
vtable	session cache context.

◆ br_ssl_server_set_policy()

static void br_ssl_server_set_policy	(	br_ssl_server_context *	cc,
		const br_ssl_server_policy_class **	pctx
	)

inlinestatic

Set an externally provided policy context.

The policy context's methods are invoked to decide the cipher suite and certificate chain, and to perform operations involving the server's private key.

Parameters

cc	server context.
pctx	policy context (pointer to its vtable field).

◆ br_ssl_server_set_single_ec()

void br_ssl_server_set_single_ec	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_ec_private_key *	sk,
		unsigned	allowed_usages,
		unsigned	cert_issuer_key_type,
		const br_ec_impl *	iec,
		br_ecdsa_sign	iecdsa
	)

Set the server certificate chain and key (single EC case).

This function uses a policy context included in the server context. It configures use of a single server certificate chain with an EC private key. The allowed_usages is a combination of usages, namely BR_KEYTYPE_KEYX and/or BR_KEYTYPE_SIGN; this enables or disables the corresponding cipher suites (i.e. TLS_ECDH_* use the EC key for key exchange, while TLS_ECDHE_ECDSA_* use the EC key for signatures).

In order to support TLS_ECDH_* cipher suites (non-ephemeral ECDH), the algorithm type of the key used by the issuing CA to sign the server's certificate must be provided, as cert_issuer_key_type parameter (this value is either BR_KEYTYPE_RSA or BR_KEYTYPE_EC).

Parameters

cc	server context.
chain	server certificate chain to send.
chain_len	chain length (number of certificates).
sk	server private key (EC).
allowed_usages	allowed private key usages.
cert_issuer_key_type	issuing CA's key type.
iec	EC core implementation.
iecdsa	ECDSA signature implementation ("asn1" format).

◆ br_ssl_server_set_single_rsa()

void br_ssl_server_set_single_rsa	(	br_ssl_server_context *	cc,
		const br_x509_certificate *	chain,
		size_t	chain_len,
		const br_rsa_private_key *	sk,
		unsigned	allowed_usages,
		br_rsa_private	irsacore,
		br_rsa_pkcs1_sign	irsasign
	)

Set the server certificate chain and key (single RSA case).

This function uses a policy context included in the server context. It configures use of a single server certificate chain with a RSA private key. The allowed_usages is a combination of usages, namely BR_KEYTYPE_KEYX and/or BR_KEYTYPE_SIGN; this enables or disables the corresponding cipher suites (i.e. TLS_RSA_* use the RSA key for key exchange, while TLS_ECDHE_RSA_* use the RSA key for signatures).

Parameters

cc	server context.
chain	server certificate chain to send to the client.
chain_len	chain length (number of certificates).
sk	server private key (RSA).
allowed_usages	allowed private key usages.
irsacore	RSA core implementation.
irsasign	RSA signature implementation (PKCS#1 v1.5).

◆ br_ssl_server_set_trust_anchor_names()

static void br_ssl_server_set_trust_anchor_names	(	br_ssl_server_context *	cc,
		const br_x500_name *	ta_names,
		size_t	num
	)

inlinestatic

Activate client certificate authentication.

The trust anchor encoded X.500 names (DN) to send to the client are provided. A client certificate will be requested and validated through the X.509 validator configured in the SSL engine. If num is 0, then client certificate authentication is disabled.

If the client does not send a certificate, or on validation failure, the handshake aborts. Unauthenticated clients can be tolerated by setting the BR_OPT_TOLERATE_NO_CLIENT_AUTH flag.

The provided array is linked in, not copied, so that pointer must remain valid as long as anchor names may be used.

Parameters

cc	server context.
ta_names	encoded trust anchor names.
num	number of encoded trust anchor names.

◆ br_ssl_server_set_trust_anchor_names_alt()

static void br_ssl_server_set_trust_anchor_names_alt	(	br_ssl_server_context *	cc,
		const br_x509_trust_anchor *	tas,
		size_t	num
	)

inlinestatic

Activate client certificate authentication.

This is a variant for br_ssl_server_set_trust_anchor_names(): the trust anchor names are provided not as an array of stand-alone names (br_x500_name structures), but as an array of trust anchors (br_x509_trust_anchor structures). The server engine itself will only use the dn field of each trust anchor. This is meant to allow defining a single array of trust anchors, to be used here and in the X.509 validation engine itself.

The provided array is linked in, not copied, so that pointer must remain valid as long as anchor names may be used.

Parameters

cc	server context.
tas	trust anchors (only names are used).
num	number of trust anchors.

◆ br_ssl_server_zero()

void br_ssl_server_zero ( br_ssl_server_context * cc )

Clear the complete contents of a SSL server context.

Everything is cleared, including the reference to the configured buffer, implementations, cipher suites and state. This is a preparatory step to assembling a custom profile.

Parameters

cc	server context to clear.

◆ br_ssl_session_cache_lru_forget()

void br_ssl_session_cache_lru_forget	(	br_ssl_session_cache_lru *	cc,
		const unsigned char *	id
	)

Forget an entry in an LRU session cache.

The session cache context must have been initialised. The entry with the provided session ID (of exactly 32 bytes) is looked for in the cache; if located, it is disabled.

Parameters

cc	session cache context.
id	session ID to forget.

◆ br_ssl_session_cache_lru_init()

void br_ssl_session_cache_lru_init	(	br_ssl_session_cache_lru *	cc,
		unsigned char *	store,
		size_t	store_len
	)

Initialise a LRU session cache with the provided storage space.

The provided storage space must remain valid as long as the cache is used. Arbitrary lengths are supported, up to 4294967295 bytes; each entry uses up exactly 100 bytes.

Parameters

cc	session cache context.
store	storage space for cached entries.
store_len	storage space length (in bytes).

◆ br_sslio_close()

int br_sslio_close ( br_sslio_context * cc )

Close the SSL connection.

This call runs the SSL closure protocol (sending a close_notify, receiving the response close_notify). When it returns, the SSL connection is finished. It is still up to the caller to manage the possible transport-level termination, if applicable (alternatively, the underlying transport stream may be reused for non-SSL messages).

Returned value is 0 on success, -1 on error. A failure by the peer to process the complete closure protocol (i.e. sending back the close_notify) is an error.

Parameters

cc	SSL wrapper context.

Returns: 0 on success, or -1 on error.

◆ br_sslio_flush()

int br_sslio_flush ( br_sslio_context * cc )

Flush pending data.

This call makes sure that any buffered application data in the provided context (including the wrapped SSL engine) has been sent to the transport medium (i.e. accepted by the low_write() callback method). If there is no such pending data, then this function does nothing (and returns a success, i.e. 0).

If the underlying transport medium has its own buffers, then it is up to the caller to ensure the corresponding flushing.

Returned value is 0 on success, -1 on error.

Parameters

cc	SSL wrapper context.

Returns: 0 on success, or -1 on error.

◆ br_sslio_init()

void br_sslio_init	(	br_sslio_context *	ctx,
		br_ssl_engine_context *	engine,
		int()(void read_context, unsigned char *data, size_t len)	low_read,
		void *	read_context,
		int()(void write_context, const unsigned char *data, size_t len)	low_write,
		void *	write_context
	)

Initialise a simplified I/O wrapper context.

The simplified I/O wrapper offers a simpler read/write API for a SSL engine (client or server), using the provided callback functions for reading data from, or writing data to, the transport medium.

The callback functions have the following semantics:

Each callback receives an opaque context value (of type void *) that the callback may use arbitrarily (or possibly ignore).
low_read() reads at least one byte, at most len bytes, from the transport medium. Read bytes shall be written in data.
low_write() writes at least one byte, at most len bytes, unto the transport medium. The bytes to write are read from data.
The len parameter is never zero, and is always lower than 20000.
The number of processed bytes (read or written) is returned. Since that number is less than 20000, it always fits on an int.
On error, the callbacks return -1. Reaching end-of-stream is an error. Errors are permanent: the SSL connection is terminated.
Callbacks SHOULD NOT return 0. This is tolerated, as long as callbacks endeavour to block for some non-negligible amount of time until at least one byte can be sent or received (if a callback returns 0, then the wrapper invokes it again immediately).
Callbacks MAY return as soon as at least one byte is processed; they MAY also insist on reading or writing all requested bytes. Since SSL is a self-terminated protocol (each record has a length header), this does not change semantics.
Callbacks need not apply any buffering (for performance) since SSL itself uses buffers.

Parameters

ctx	wrapper context to initialise.
engine	SSL engine to wrap.
low_read	callback for reading data from the transport.
read_context	context pointer for `low_read()`.
low_write	callback for writing data on the transport.
write_context	context pointer for `low_write()`.

◆ br_sslio_read()

int br_sslio_read	(	br_sslio_context *	cc,
		void *	dst,
		size_t	len
	)

Read some application data from a SSL connection.

If len is zero, then this function returns 0 immediately. In all other cases, it never returns 0.

This call returns only when at least one byte has been obtained. Returned value is the number of bytes read, or -1 on error. The number of bytes always fits on an 'int' (data from a single SSL/TLS record is returned).

On error or SSL closure, this function returns -1. The caller should inspect the error status on the SSL engine to distinguish between normal closure and error.

Parameters

cc	SSL wrapper context.
dst	destination buffer for application data.
len	maximum number of bytes to obtain.

Returns: number of bytes obtained, or -1 on error.

◆ br_sslio_read_all()

int br_sslio_read_all	(	br_sslio_context *	cc,
		void *	dst,
		size_t	len
	)

Read application data from a SSL connection.

This calls returns only when all requested len bytes are read, or an error is reached. Returned value is 0 on success, -1 on error. A normal (verified) SSL closure before that many bytes are obtained is reported as an error by this function.

Parameters

cc	SSL wrapper context.
dst	destination buffer for application data.
len	number of bytes to obtain.

Returns: 0 on success, or -1 on error.

◆ br_sslio_write()

int br_sslio_write	(	br_sslio_context *	cc,
		const void *	src,
		size_t	len
	)

Write some application data unto a SSL connection.

If len is zero, then this function returns 0 immediately. In all other cases, it never returns 0.

This call returns only when at least one byte has been written. Returned value is the number of bytes written, or -1 on error. The number of bytes always fits on an 'int' (less than 20000).

On error or SSL closure, this function returns -1. The caller should inspect the error status on the SSL engine to distinguish between normal closure and error.

Important: SSL is buffered; a "written" byte is a byte that was injected into the wrapped SSL engine, but this does not necessarily mean that it has been scheduled for sending. Use br_sslio_flush() to ensure that all pending data has been sent to the transport medium.

Parameters

cc	SSL wrapper context.
src	source buffer for application data.
len	maximum number of bytes to write.

Returns: number of bytes written, or -1 on error.

◆ br_sslio_write_all()

int br_sslio_write_all	(	br_sslio_context *	cc,
		const void *	src,
		size_t	len
	)

Write application data unto a SSL connection.

This calls returns only when all requested len bytes have been written, or an error is reached. Returned value is 0 on success, -1 on error. A normal (verified) SSL closure before that many bytes are written is reported as an error by this function.

Important: SSL is buffered; a "written" byte is a byte that was injected into the wrapped SSL engine, but this does not necessarily mean that it has been scheduled for sending. Use br_sslio_flush() to ensure that all pending data has been sent to the transport medium.

Parameters

cc	SSL wrapper context.
src	source buffer for application data.
len	number of bytes to write.

Returns: 0 on success, or -1 on error.

Variable Documentation

◆ br_sslrec_in_cbc_vtable

const br_sslrec_in_cbc_class br_sslrec_in_cbc_vtable

Static, constant vtable for record decryption with CBC.

◆ br_sslrec_in_ccm_vtable

const br_sslrec_in_ccm_class br_sslrec_in_ccm_vtable

Static, constant vtable for record decryption with CCM.

◆ br_sslrec_in_chapol_vtable

const br_sslrec_in_chapol_class br_sslrec_in_chapol_vtable

Static, constant vtable for record decryption with ChaCha20+Poly1305.

◆ br_sslrec_in_gcm_vtable

const br_sslrec_in_gcm_class br_sslrec_in_gcm_vtable

Static, constant vtable for record decryption with GCM.

◆ br_sslrec_out_cbc_vtable

const br_sslrec_out_cbc_class br_sslrec_out_cbc_vtable

Static, constant vtable for record encryption with CBC.

◆ br_sslrec_out_ccm_vtable

const br_sslrec_out_ccm_class br_sslrec_out_ccm_vtable

Static, constant vtable for record encryption with CCM.

◆ br_sslrec_out_chapol_vtable

const br_sslrec_out_chapol_class br_sslrec_out_chapol_vtable

Static, constant vtable for record encryption with ChaCha20+Poly1305.

◆ br_sslrec_out_clear_vtable

const br_sslrec_out_class br_sslrec_out_clear_vtable

Static, constant vtable for the no-encryption engine.

◆ br_sslrec_out_gcm_vtable

const br_sslrec_out_gcm_class br_sslrec_out_gcm_vtable

Static, constant vtable for record encryption with GCM.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

SSL

Macro Definition Documentation

◆ BR_ALERT_ACCESS_DENIED

◆ BR_ALERT_BAD_CERTIFICATE

◆ BR_ALERT_BAD_RECORD_MAC

◆ BR_ALERT_CERTIFICATE_EXPIRED

◆ BR_ALERT_CERTIFICATE_REVOKED

◆ BR_ALERT_CERTIFICATE_UNKNOWN

◆ BR_ALERT_CLOSE_NOTIFY

◆ BR_ALERT_DECODE_ERROR

◆ BR_ALERT_DECOMPRESSION_FAILURE

◆ BR_ALERT_DECRYPT_ERROR

◆ BR_ALERT_HANDSHAKE_FAILURE

◆ BR_ALERT_ILLEGAL_PARAMETER

◆ BR_ALERT_INSUFFICIENT_SECURITY

◆ BR_ALERT_INTERNAL_ERROR

◆ BR_ALERT_NO_APPLICATION_PROTOCOL

◆ BR_ALERT_NO_RENEGOTIATION

◆ BR_ALERT_PROTOCOL_VERSION

◆ BR_ALERT_RECORD_OVERFLOW

◆ BR_ALERT_UNEXPECTED_MESSAGE

◆ BR_ALERT_UNKNOWN_CA

◆ BR_ALERT_UNSUPPORTED_CERTIFICATE

◆ BR_ALERT_UNSUPPORTED_EXTENSION

◆ BR_ALERT_USER_CANCELED

◆ BR_AUTH_ECDH

◆ BR_AUTH_ECDSA

◆ BR_AUTH_RSA

◆ BR_ERR_BAD_ALERT

◆ BR_ERR_BAD_CCS

◆ BR_ERR_BAD_CIPHER_SUITE

◆ BR_ERR_BAD_COMPRESSION

◆ BR_ERR_BAD_FINISHED

◆ BR_ERR_BAD_FRAGLEN

◆ BR_ERR_BAD_HANDSHAKE

◆ BR_ERR_BAD_HELLO_DONE

◆ BR_ERR_BAD_LENGTH

◆ BR_ERR_BAD_MAC

◆ BR_ERR_BAD_PARAM

◆ BR_ERR_BAD_SECRENEG

◆ BR_ERR_BAD_SIGNATURE

◆ BR_ERR_BAD_SNI

◆ BR_ERR_BAD_STATE

◆ BR_ERR_BAD_VERSION

◆ BR_ERR_EXTRA_EXTENSION

◆ BR_ERR_INVALID_ALGORITHM

◆ BR_ERR_IO

◆ BR_ERR_LIMIT_EXCEEDED

◆ BR_ERR_NO_CLIENT_AUTH

◆ BR_ERR_NO_RANDOM

◆ BR_ERR_OK

◆ BR_ERR_OVERSIZED_ID

◆ BR_ERR_RECV_FATAL_ALERT

◆ BR_ERR_RESUME_MISMATCH

◆ BR_ERR_SEND_FATAL_ALERT

◆ BR_ERR_TOO_LARGE

◆ BR_ERR_UNEXPECTED

◆ BR_ERR_UNKNOWN_TYPE

◆ BR_ERR_UNSUPPORTED_VERSION

◆ BR_ERR_WRONG_KEY_USAGE

◆ BR_OPT_ENFORCE_SERVER_PREFERENCES

◆ BR_OPT_FAIL_ON_ALPN_MISMATCH

◆ BR_OPT_NO_RENEGOTIATION

◆ BR_OPT_TOLERATE_NO_CLIENT_AUTH

◆ BR_SSL30

◆ BR_SSL_BUFSIZE_BIDI

◆ BR_SSL_BUFSIZE_INPUT

◆ BR_SSL_BUFSIZE_MONO

◆ BR_SSL_BUFSIZE_OUTPUT

◆ BR_SSL_CLOSED

◆ BR_SSL_RECVAPP

◆ BR_SSL_RECVREC

◆ BR_SSL_SENDAPP

◆ BR_SSL_SENDREC