BearSSL

Data Structures | Macros | Typedefs | Functions | Variables
bearssl_ssl.h File Reference
Include dependency graph for bearssl_ssl.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of 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 | ) |
| inline static

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 | ) |
| inline static

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 | ) |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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 | ) |
| inline static

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 | ) |
| inline static

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 | ) |
| inline static

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 | ) |
| inline static

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
| ) |  |
| inline static

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 | ) |
| inline static

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 | ) |
| inline static

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 | ) |
| inline static

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
| ) |  |
| inline static

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 | ) |
| inline static

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 | ) |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

## ◆ 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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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 | ) |
| inline static

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 | ) |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| ) |  |
| inline static

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
| extern

Static, constant vtable for record decryption with CBC.

## ◆ br_sslrec_in_ccm_vtable

const br_sslrec_in_ccm_class br_sslrec_in_ccm_vtable
| extern

Static, constant vtable for record decryption with CCM.

## ◆ br_sslrec_in_chapol_vtable

const br_sslrec_in_chapol_class br_sslrec_in_chapol_vtable
| extern

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
| extern

Static, constant vtable for record decryption with GCM.

## ◆ br_sslrec_out_cbc_vtable

const br_sslrec_out_cbc_class br_sslrec_out_cbc_vtable
| extern

Static, constant vtable for record encryption with CBC.

## ◆ br_sslrec_out_ccm_vtable

const br_sslrec_out_ccm_class br_sslrec_out_ccm_vtable
| extern

Static, constant vtable for record encryption with CCM.

## ◆ br_sslrec_out_chapol_vtable

const br_sslrec_out_chapol_class br_sslrec_out_chapol_vtable
| extern

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

## ◆ br_sslrec_out_clear_vtable

const br_sslrec_out_class br_sslrec_out_clear_vtable
| extern

Static, constant vtable for the no-encryption engine.

## ◆ br_sslrec_out_gcm_vtable

const br_sslrec_out_gcm_class br_sslrec_out_gcm_vtable
| extern

Static, constant vtable for record encryption with GCM.