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_implbr_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_translatedbr_ssl_server_get_client_suites (const br_ssl_server_context *cc, size_t *num)
 Get the supported client suites. More...
 
static uint32_t br_ssl_server_get_client_hashes (const br_ssl_server_context *cc)
 Get the hash functions and signature algorithms supported by the client. More...
 
static uint32_t br_ssl_server_get_client_curves (const br_ssl_server_context *cc)
 Get the elliptic curves supported by the client. More...
 
void br_ssl_server_zero (br_ssl_server_context *cc)
 Clear the complete contents of a SSL server context. More...
 
static void br_ssl_server_set_policy (br_ssl_server_context *cc, const br_ssl_server_policy_class **pctx)
 Set an externally provided policy context. More...
 
void br_ssl_server_set_single_rsa (br_ssl_server_context *cc, const br_x509_certificate *chain, size_t chain_len, const br_rsa_private_key *sk, unsigned allowed_usages, br_rsa_private irsacore, br_rsa_pkcs1_sign irsasign)
 Set the server certificate chain and key (single RSA case). More...
 
void br_ssl_server_set_single_ec (br_ssl_server_context *cc, const br_x509_certificate *chain, size_t chain_len, const br_ec_private_key *sk, unsigned allowed_usages, unsigned cert_issuer_key_type, const br_ec_impl *iec, br_ecdsa_sign iecdsa)
 Set the server certificate chain and key (single EC case). More...
 
static void br_ssl_server_set_trust_anchor_names (br_ssl_server_context *cc, const br_x500_name *ta_names, size_t num)
 Activate client certificate authentication. More...
 
static void br_ssl_server_set_trust_anchor_names_alt (br_ssl_server_context *cc, const br_x509_trust_anchor *tas, size_t num)
 Activate client certificate authentication. More...
 
static void br_ssl_server_set_cache (br_ssl_server_context *cc, const br_ssl_session_cache_class **vtable)
 Configure the cache for session parameters. More...
 
int br_ssl_server_reset (br_ssl_server_context *cc)
 Prepare or reset a server context for handling an incoming client. More...
 
void br_sslio_init (br_sslio_context *ctx, br_ssl_engine_context *engine, int(*low_read)(void *read_context, unsigned char *data, size_t len), void *read_context, int(*low_write)(void *write_context, const unsigned char *data, size_t len), void *write_context)
 Initialise a simplified I/O wrapper context. More...
 
int br_sslio_read (br_sslio_context *cc, void *dst, size_t len)
 Read some application data from a SSL connection. More...
 
int br_sslio_read_all (br_sslio_context *cc, void *dst, size_t len)
 Read application data from a SSL connection. More...
 
int br_sslio_write (br_sslio_context *cc, const void *src, size_t len)
 Write some application data unto a SSL connection. More...
 
int br_sslio_write_all (br_sslio_context *cc, const void *src, size_t len)
 Write application data unto a SSL connection. More...
 
int br_sslio_flush (br_sslio_context *cc)
 Flush pending data. More...
 
int br_sslio_close (br_sslio_context *cc)
 Close the SSL connection. More...
 

Variables

const br_sslrec_out_class br_sslrec_out_clear_vtable
 Static, constant vtable for the no-encryption engine. More...
 
const br_sslrec_in_cbc_class br_sslrec_in_cbc_vtable
 Static, constant vtable for record decryption with CBC. More...
 
const br_sslrec_out_cbc_class br_sslrec_out_cbc_vtable
 Static, constant vtable for record encryption with CBC. More...
 
const br_sslrec_in_gcm_class br_sslrec_in_gcm_vtable
 Static, constant vtable for record decryption with GCM. More...
 
const br_sslrec_out_gcm_class br_sslrec_out_gcm_vtable
 Static, constant vtable for record encryption with GCM. More...
 
const br_sslrec_in_chapol_class br_sslrec_in_chapol_vtable
 Static, constant vtable for record decryption with ChaCha20+Poly1305. More...
 
const br_sslrec_out_chapol_class br_sslrec_out_chapol_vtable
 Static, constant vtable for record encryption with ChaCha20+Poly1305. More...
 
const br_sslrec_in_ccm_class br_sslrec_in_ccm_vtable
 Static, constant vtable for record decryption with CCM. More...
 
const br_sslrec_out_ccm_class br_sslrec_out_ccm_vtable
 Static, constant vtable for record encryption with CCM. More...
 

Detailed Description

SSL

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

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

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

Macro Definition Documentation

◆ BR_ALERT_ACCESS_DENIED

#define BR_ALERT_ACCESS_DENIED   49

◆ BR_ALERT_BAD_CERTIFICATE

#define BR_ALERT_BAD_CERTIFICATE   42

◆ BR_ALERT_BAD_RECORD_MAC

#define BR_ALERT_BAD_RECORD_MAC   20

◆ BR_ALERT_CERTIFICATE_EXPIRED

#define BR_ALERT_CERTIFICATE_EXPIRED   45

◆ BR_ALERT_CERTIFICATE_REVOKED

#define BR_ALERT_CERTIFICATE_REVOKED   44

◆ BR_ALERT_CERTIFICATE_UNKNOWN

#define BR_ALERT_CERTIFICATE_UNKNOWN   46

◆ BR_ALERT_CLOSE_NOTIFY

#define BR_ALERT_CLOSE_NOTIFY   0

◆ BR_ALERT_DECODE_ERROR

#define BR_ALERT_DECODE_ERROR   50

◆ BR_ALERT_DECOMPRESSION_FAILURE

#define BR_ALERT_DECOMPRESSION_FAILURE   30

◆ BR_ALERT_DECRYPT_ERROR

#define BR_ALERT_DECRYPT_ERROR   51

◆ BR_ALERT_HANDSHAKE_FAILURE

#define BR_ALERT_HANDSHAKE_FAILURE   40

◆ BR_ALERT_ILLEGAL_PARAMETER

#define BR_ALERT_ILLEGAL_PARAMETER   47

◆ BR_ALERT_INSUFFICIENT_SECURITY

#define BR_ALERT_INSUFFICIENT_SECURITY   71

◆ BR_ALERT_INTERNAL_ERROR

#define BR_ALERT_INTERNAL_ERROR   80

◆ BR_ALERT_NO_APPLICATION_PROTOCOL

#define BR_ALERT_NO_APPLICATION_PROTOCOL   120

◆ BR_ALERT_NO_RENEGOTIATION

#define BR_ALERT_NO_RENEGOTIATION   100

◆ BR_ALERT_PROTOCOL_VERSION

#define BR_ALERT_PROTOCOL_VERSION   70

◆ BR_ALERT_RECORD_OVERFLOW

#define BR_ALERT_RECORD_OVERFLOW   22

◆ BR_ALERT_UNEXPECTED_MESSAGE

#define BR_ALERT_UNEXPECTED_MESSAGE   10

◆ BR_ALERT_UNKNOWN_CA

#define BR_ALERT_UNKNOWN_CA   48

◆ BR_ALERT_UNSUPPORTED_CERTIFICATE

#define BR_ALERT_UNSUPPORTED_CERTIFICATE   43

◆ BR_ALERT_UNSUPPORTED_EXTENSION

#define BR_ALERT_UNSUPPORTED_EXTENSION   110

◆ BR_ALERT_USER_CANCELED

#define BR_ALERT_USER_CANCELED   90

◆ BR_AUTH_ECDH

#define BR_AUTH_ECDH   0

Client authentication type: static ECDH.

◆ BR_AUTH_ECDSA

#define BR_AUTH_ECDSA   3

Client authentication type: ECDSA signature.

◆ BR_AUTH_RSA

#define BR_AUTH_RSA   1

Client authentication type: RSA signature.

◆ BR_ERR_BAD_ALERT

#define BR_ERR_BAD_ALERT   13

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

◆ BR_ERR_BAD_CCS

#define BR_ERR_BAD_CCS   12

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

◆ BR_ERR_BAD_CIPHER_SUITE

#define BR_ERR_BAD_CIPHER_SUITE   16

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

◆ BR_ERR_BAD_COMPRESSION

#define BR_ERR_BAD_COMPRESSION   17

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

◆ BR_ERR_BAD_FINISHED

#define BR_ERR_BAD_FINISHED   24

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

◆ BR_ERR_BAD_FRAGLEN

#define BR_ERR_BAD_FRAGLEN   18

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

◆ BR_ERR_BAD_HANDSHAKE

#define BR_ERR_BAD_HANDSHAKE   14

SSL status: incoming handshake message decoding failed.

◆ BR_ERR_BAD_HELLO_DONE

#define BR_ERR_BAD_HELLO_DONE   22

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

◆ BR_ERR_BAD_LENGTH

#define BR_ERR_BAD_LENGTH   5

SSL status: incoming record length is invalid.

◆ BR_ERR_BAD_MAC

#define BR_ERR_BAD_MAC   7

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

◆ BR_ERR_BAD_PARAM

#define BR_ERR_BAD_PARAM   1

SSL status: caller-provided parameter is incorrect.

◆ BR_ERR_BAD_SECRENEG

#define BR_ERR_BAD_SECRENEG   19

SSL status: secure renegotiation failed.

◆ BR_ERR_BAD_SIGNATURE

#define BR_ERR_BAD_SIGNATURE   27

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

◆ BR_ERR_BAD_SNI

#define BR_ERR_BAD_SNI   21

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

◆ BR_ERR_BAD_STATE

#define BR_ERR_BAD_STATE   2

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

◆ BR_ERR_BAD_VERSION

#define BR_ERR_BAD_VERSION   4

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

◆ BR_ERR_EXTRA_EXTENSION

#define BR_ERR_EXTRA_EXTENSION   20

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

◆ BR_ERR_INVALID_ALGORITHM

#define BR_ERR_INVALID_ALGORITHM   26

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

◆ BR_ERR_IO

#define BR_ERR_IO   31

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

◆ BR_ERR_LIMIT_EXCEEDED

#define BR_ERR_LIMIT_EXCEEDED   23

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

◆ BR_ERR_NO_CLIENT_AUTH

#define BR_ERR_NO_CLIENT_AUTH   29

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

◆ BR_ERR_NO_RANDOM

#define BR_ERR_NO_RANDOM   8

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

◆ BR_ERR_OK

#define BR_ERR_OK   0

SSL status: no error so far (0).

◆ BR_ERR_OVERSIZED_ID

#define BR_ERR_OVERSIZED_ID   15

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

◆ BR_ERR_RECV_FATAL_ALERT

#define BR_ERR_RECV_FATAL_ALERT   256

SSL status: base value for a received fatal alert.

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

◆ BR_ERR_RESUME_MISMATCH

#define BR_ERR_RESUME_MISMATCH   25

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

◆ BR_ERR_SEND_FATAL_ALERT

#define BR_ERR_SEND_FATAL_ALERT   512

SSL status: base value for a sent fatal alert.

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

◆ BR_ERR_TOO_LARGE

#define BR_ERR_TOO_LARGE   6

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

◆ BR_ERR_UNEXPECTED

#define BR_ERR_UNEXPECTED   10

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

◆ BR_ERR_UNKNOWN_TYPE

#define BR_ERR_UNKNOWN_TYPE   9

SSL status: incoming record type is unknown.

◆ BR_ERR_UNSUPPORTED_VERSION

#define BR_ERR_UNSUPPORTED_VERSION   3

SSL status: incoming protocol or record version is unsupported.

◆ BR_ERR_WRONG_KEY_USAGE

#define BR_ERR_WRONG_KEY_USAGE   28

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

◆ BR_OPT_ENFORCE_SERVER_PREFERENCES

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

Behavioural flag: enforce server preferences.

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

◆ BR_OPT_FAIL_ON_ALPN_MISMATCH

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

Behavioural flag: fail on application protocol mismatch.

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

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

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

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

◆ BR_OPT_NO_RENEGOTIATION

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

Behavioural flag: disable renegotiation.

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

◆ BR_OPT_TOLERATE_NO_CLIENT_AUTH

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

Behavioural flag: tolerate lack of client authentication.

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

Notes:

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

◆ BR_SSL30

#define BR_SSL30   0x0300

Protocol version: SSL 3.0 (unsupported).

◆ BR_SSL_BUFSIZE_BIDI

#define BR_SSL_BUFSIZE_BIDI   (BR_SSL_BUFSIZE_INPUT + BR_SSL_BUFSIZE_OUTPUT)

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

◆ BR_SSL_BUFSIZE_INPUT

#define BR_SSL_BUFSIZE_INPUT   (16384 + 325)

Optimal input buffer size.

◆ BR_SSL_BUFSIZE_MONO

#define BR_SSL_BUFSIZE_MONO   BR_SSL_BUFSIZE_INPUT

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

◆ BR_SSL_BUFSIZE_OUTPUT

#define BR_SSL_BUFSIZE_OUTPUT   (16384 + 85)

Optimal output buffer size.

◆ BR_SSL_CLOSED

#define BR_SSL_CLOSED   0x0001

SSL engine state: closed or failed.

◆ BR_SSL_RECVAPP

#define BR_SSL_RECVAPP   0x0010

SSL engine state: engine has received application data.

◆ BR_SSL_RECVREC

#define BR_SSL_RECVREC   0x0004

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

◆ BR_SSL_SENDAPP

#define BR_SSL_SENDAPP   0x0008

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

◆ BR_SSL_SENDREC

#define BR_SSL_SENDREC   0x0002

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

◆ BR_TLS10

#define BR_TLS10   0x0301

Protocol version: TLS 1.0.

◆ BR_TLS11

#define BR_TLS11   0x0302

Protocol version: TLS 1.1.

◆ BR_TLS12

#define BR_TLS12   0x0303

Protocol version: TLS 1.2.

◆ BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA   0x001B

◆ BR_TLS_DH_anon_WITH_AES_128_CBC_SHA

#define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA   0x0034

◆ BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256

#define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256   0x006C

◆ BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256

#define BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256   0x00A6

◆ BR_TLS_DH_anon_WITH_AES_256_CBC_SHA

#define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA   0x003A

◆ BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256

#define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256   0x006D

◆ BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384

#define BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384   0x00A7

◆ BR_TLS_DH_anon_WITH_RC4_128_MD5

#define BR_TLS_DH_anon_WITH_RC4_128_MD5   0x0018

◆ BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA   0x000D

◆ BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA

#define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA   0x0030

◆ BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256

#define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256   0x003E

◆ BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256

#define BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256   0x00A4

◆ BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA

#define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA   0x0036

◆ BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256

#define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256   0x0068

◆ BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384

#define BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384   0x00A5

◆ BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA   0x0010

◆ BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA   0x0031

◆ BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256   0x003F

◆ BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256   0x00A0

◆ BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA   0x0037

◆ BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256

#define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256   0x0069

◆ BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384   0x00A1

◆ BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA   0x0013

◆ BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA

#define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA   0x0032

◆ BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256

#define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256   0x0040

◆ BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256

#define BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256   0x00A2

◆ BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA

#define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA   0x0038

◆ BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256

#define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256   0x006A

◆ BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384

#define BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384   0x00A3

◆ BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256   0xCCAD

◆ BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA   0x0016

◆ BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA   0x0033

◆ BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256   0x0067

◆ BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256   0x009E

◆ BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA   0x0039

◆ BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256

#define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256   0x006B

◆ BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384   0x009F

◆ BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256   0xCCAA

◆ BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA   0xC017

◆ BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA   0xC018

◆ BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA   0xC019

◆ BR_TLS_ECDH_anon_WITH_NULL_SHA

#define BR_TLS_ECDH_anon_WITH_NULL_SHA   0xC015

◆ BR_TLS_ECDH_anon_WITH_RC4_128_SHA

#define BR_TLS_ECDH_anon_WITH_RC4_128_SHA   0xC016

◆ BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA   0xC003

◆ BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA   0xC004

◆ BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256   0xC025

◆ BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256   0xC02D

◆ BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA   0xC005

◆ BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384

#define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384   0xC026

◆ BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384   0xC02E

◆ BR_TLS_ECDH_ECDSA_WITH_NULL_SHA

#define BR_TLS_ECDH_ECDSA_WITH_NULL_SHA   0xC001

◆ BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA

#define BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA   0xC002

◆ BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA   0xC00D

◆ BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA   0xC00E

◆ BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256   0xC029

◆ BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256   0xC031

◆ BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA   0xC00F

◆ BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384

#define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384   0xC02A

◆ BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384   0xC032

◆ BR_TLS_ECDH_RSA_WITH_NULL_SHA

#define BR_TLS_ECDH_RSA_WITH_NULL_SHA   0xC00B

◆ BR_TLS_ECDH_RSA_WITH_RC4_128_SHA

#define BR_TLS_ECDH_RSA_WITH_RC4_128_SHA   0xC00C

◆ BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA   0xC008

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA   0xC009

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256   0xC023

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM   0xC0AC

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8   0xC0AE

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256   0xC02B

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA   0xC00A

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384   0xC024

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM   0xC0AD

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8   0xC0AF

◆ BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384   0xC02C

◆ BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256   0xCCA9

◆ BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA   0xC006

◆ BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA

#define BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA   0xC007

◆ BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256   0xCCAC

◆ BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA   0xC012

◆ BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA   0xC013

◆ BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256   0xC027

◆ BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   0xC02F

◆ BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA   0xC014

◆ BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

#define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384   0xC028

◆ BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384   0xC030

◆ BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256   0xCCA8

◆ BR_TLS_ECDHE_RSA_WITH_NULL_SHA

#define BR_TLS_ECDHE_RSA_WITH_NULL_SHA   0xC010

◆ BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA

#define BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA   0xC011

◆ BR_TLS_FALLBACK_SCSV

#define BR_TLS_FALLBACK_SCSV   0x5600

◆ BR_TLS_NULL_WITH_NULL_NULL

#define BR_TLS_NULL_WITH_NULL_NULL   0x0000

◆ BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256   0xCCAB

◆ BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256

#define BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256   0xCCAE

◆ BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA

#define BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA   0x000A

◆ BR_TLS_RSA_WITH_AES_128_CBC_SHA

#define BR_TLS_RSA_WITH_AES_128_CBC_SHA   0x002F

◆ BR_TLS_RSA_WITH_AES_128_CBC_SHA256

#define BR_TLS_RSA_WITH_AES_128_CBC_SHA256   0x003C

◆ BR_TLS_RSA_WITH_AES_128_CCM

#define BR_TLS_RSA_WITH_AES_128_CCM   0xC09C

◆ BR_TLS_RSA_WITH_AES_128_CCM_8

#define BR_TLS_RSA_WITH_AES_128_CCM_8   0xC0A0

◆ BR_TLS_RSA_WITH_AES_128_GCM_SHA256

#define BR_TLS_RSA_WITH_AES_128_GCM_SHA256   0x009C

◆ BR_TLS_RSA_WITH_AES_256_CBC_SHA

#define BR_TLS_RSA_WITH_AES_256_CBC_SHA   0x0035

◆ BR_TLS_RSA_WITH_AES_256_CBC_SHA256

#define BR_TLS_RSA_WITH_AES_256_CBC_SHA256   0x003D

◆ BR_TLS_RSA_WITH_AES_256_CCM

#define BR_TLS_RSA_WITH_AES_256_CCM   0xC09D

◆ BR_TLS_RSA_WITH_AES_256_CCM_8

#define BR_TLS_RSA_WITH_AES_256_CCM_8   0xC0A1

◆ BR_TLS_RSA_WITH_AES_256_GCM_SHA384

#define BR_TLS_RSA_WITH_AES_256_GCM_SHA384   0x009D

◆ BR_TLS_RSA_WITH_NULL_MD5

#define BR_TLS_RSA_WITH_NULL_MD5   0x0001

◆ BR_TLS_RSA_WITH_NULL_SHA

#define BR_TLS_RSA_WITH_NULL_SHA   0x0002

◆ BR_TLS_RSA_WITH_NULL_SHA256

#define BR_TLS_RSA_WITH_NULL_SHA256   0x003B

◆ BR_TLS_RSA_WITH_RC4_128_MD5

#define BR_TLS_RSA_WITH_RC4_128_MD5   0x0004

◆ BR_TLS_RSA_WITH_RC4_128_SHA

#define BR_TLS_RSA_WITH_RC4_128_SHA   0x0005

Typedef Documentation

◆ br_suite_translated

typedef uint16_t br_suite_translated[2]

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

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

  • Bits 12 to 15: key exchange + server key type
val symbolic constant suite type details
0 BR_SSLKEYX_RSA RSA RSA key exchange, key is RSA (encryption)
1 BR_SSLKEYX_ECDHE_RSA ECDHE_RSA ECDHE key exchange, key is RSA (signature)
2 BR_SSLKEYX_ECDHE_ECDSA ECDHE_ECDSA ECDHE key exchange, key is EC (signature)
3 BR_SSLKEYX_ECDH_RSA ECDH_RSA Key is EC (key exchange), cert signed with RSA
4 BR_SSLKEYX_ECDH_ECDSA ECDH_ECDSA Key is EC (key exchange), cert signed with ECDSA
  • Bits 8 to 11: symmetric encryption algorithm
val symbolic constant symmetric encryption key strength (bits)
0 BR_SSLENC_3DES_CBC 3DES/CBC 168
1 BR_SSLENC_AES128_CBC AES-128/CBC 128
2 BR_SSLENC_AES256_CBC AES-256/CBC 256
3 BR_SSLENC_AES128_GCM AES-128/GCM 128
4 BR_SSLENC_AES256_GCM AES-256/GCM 256
5 BR_SSLENC_CHACHA20 ChaCha20/Poly1305 256
  • Bits 4 to 7: MAC algorithm
val symbolic constant MAC type details
0 BR_SSLMAC_AEAD AEAD No dedicated MAC (encryption is AEAD)
2 BR_SSLMAC_SHA1 HMAC/SHA-1 Value matches br_sha1_ID
4 BR_SSLMAC_SHA256 HMAC/SHA-256 Value matches br_sha256_ID
5 BR_SSLMAC_SHA384 HMAC/SHA-384 Value matches br_sha384_ID
  • Bits 0 to 3: hash function for PRF when used with TLS-1.2
val symbolic constant hash function details
4 BR_SSLPRF_SHA256 SHA-256 Value matches br_sha256_ID
5 BR_SSLPRF_SHA384 SHA-384 Value matches br_sha384_ID

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

Function Documentation

◆ br_ssl_client_forget_session()

static void br_ssl_client_forget_session ( br_ssl_client_context *  cc)
inlinestatic

Forget any session in the context.

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

Parameters
ccclient context.

◆ br_ssl_client_get_server_curve()

static int br_ssl_client_get_server_curve ( const br_ssl_client_context *  cc)
inlinestatic

Get the server key curve.

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

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

◆ br_ssl_client_get_server_hashes()

static uint32_t br_ssl_client_get_server_hashes ( const br_ssl_client_context *  cc)
inlinestatic

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

This value is a bit field:

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

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

Parameters
ccclient 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
ccclient context to initialise.
xcX.509 validation context to initialise.
trust_anchorstrust anchors to use.
trust_anchors_numnumber 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
ccclient context.
server_nametarget server name, or NULL.
resume_sessionnon-zero to try session resumption.
Returns
0 on failure, 1 on success.

◆ br_ssl_client_set_client_certificate()

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

Set an externally provided client certificate handler context.

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

Parameters
ccclient context.
pctxcertificate 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
ccclient context.

◆ br_ssl_client_set_min_clienthello_len()

static void br_ssl_client_set_min_clienthello_len ( br_ssl_client_context *  cc,
uint16_t  len 
)
inlinestatic

Set the minimum ClientHello length (RFC 7685 padding).

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

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

Parameters
ccclient context.
lenminimum ClientHello length (in bytes).

◆ br_ssl_client_set_rsapub()

static void br_ssl_client_set_rsapub ( br_ssl_client_context *  cc,
br_rsa_public  irsapub 
)
inlinestatic

Set the RSA public-key operations implementation.

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

Parameters
ccclient context.
irsapubRSA 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
ccSSL client context.
chainclient certificate chain (SSL order: EE comes first).
chain_lenclient chain length (number of certificates).
skclient private key.
irsasignRSA 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
ccclient context to clear.

◆ br_ssl_engine_add_flags()

static void br_ssl_engine_add_flags ( br_ssl_engine_context cc,
uint32_t  flags 
)
inlinestatic

Set some engine behavioural flags.

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

Parameters
ccSSL engine context.
flagsadditional 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
ccSSL 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
ccSSL 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
ccSSL engine context.
forcenon-zero to force sending an empty record.

◆ br_ssl_engine_get_ec()

static const br_ec_impl* br_ssl_engine_get_ec ( br_ssl_engine_context cc)
inlinestatic

Get the EC implementation configured in the provided engine.

Parameters
ccSSL engine context.
Returns
the EC implementation.

◆ br_ssl_engine_get_ecdhe_curve()

static int br_ssl_engine_get_ecdhe_curve ( br_ssl_engine_context cc)
inlinestatic

Get identifier for the curve used for key exchange.

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

Parameters
ccSSL engine context.
Returns
the ECDHE curve identifier.

◆ br_ssl_engine_get_ecdsa()

static br_ecdsa_vrfy br_ssl_engine_get_ecdsa ( br_ssl_engine_context cc)
inlinestatic

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

Parameters
ccSSL engine context.
Returns
the ECDSA signature verification implementation.

◆ br_ssl_engine_get_flags()

static uint32_t br_ssl_engine_get_flags ( br_ssl_engine_context cc)
inlinestatic

Get currently defined engine behavioural flags.

Parameters
ccSSL engine context.
Returns
the flags.

◆ br_ssl_engine_get_hash()

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

Get a hash function implementation (by ID).

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

Parameters
ctxSSL engine context.
idhash function identifier.
Returns
the hash function implementation (or NULL).

◆ br_ssl_engine_get_rsavrfy()

static br_rsa_pkcs1_vrfy br_ssl_engine_get_rsavrfy ( br_ssl_engine_context cc)
inlinestatic

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

Parameters
ccSSL engine context.
Returns
the RSA signature verification implementation.

◆ br_ssl_engine_get_selected_protocol()

static const char* br_ssl_engine_get_selected_protocol ( br_ssl_engine_context ctx)
inlinestatic

Get the selected protocol.

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

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

Returns
the selected protocol, or NULL.

◆ br_ssl_engine_get_server_name()

static const char* br_ssl_engine_get_server_name ( const br_ssl_engine_context cc)
inlinestatic

Get the "server name" in this engine.

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

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

Parameters
ccSSL engine context.
Returns
the server name (possibly empty).

◆ br_ssl_engine_get_session_parameters()

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

Get a copy of the session parameters.

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

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

Parameters
ccSSL engine context.
ppdestination structure for the session parameters.

◆ br_ssl_engine_get_version()

static unsigned br_ssl_engine_get_version ( const br_ssl_engine_context cc)
inlinestatic

Get the protocol version.

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

Parameters
ccSSL 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
ccSSL engine context.
dataextra entropy to inject.
lenlength of the extra data (in bytes).

◆ br_ssl_engine_last_error()

static int br_ssl_engine_last_error ( const br_ssl_engine_context cc)
inlinestatic

Get the engine error indicator.

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

Parameters
ccSSL 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
ccSSL engine context.
lennumber 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
ccSSL engine context.
lenreceives 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
ccSSL engine context.
lennumber 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
ccSSL engine context.
lenreceives the record data input buffer length, or 0.
Returns
the record data input buffer, or NULL.

◆ br_ssl_engine_remove_flags()

static void br_ssl_engine_remove_flags ( br_ssl_engine_context cc,
uint32_t  flags 
)
inlinestatic

Clear some engine behavioural flags.

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

Parameters
ccSSL engine context.
flagsflags 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
ccSSL 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
ccSSL engine context.
lennumber 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
ccSSL engine context.
lenreceives 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
ccSSL engine context.
lennumber 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
ccSSL engine context.
lenreceives the record data output buffer length, or 0.
Returns
the record data output buffer, or NULL.

◆ br_ssl_engine_set_aes_cbc()

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

Set the AES/CBC implementations.

Parameters
ccSSL engine context.
impl_encAES/CBC encryption implementation (or NULL).
impl_decAES/CBC decryption implementation (or NULL).

◆ br_ssl_engine_set_aes_ctr()

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

Set the AES/CTR implementation.

Parameters
ccSSL engine context.
implAES/CTR encryption/decryption implementation (or NULL).

◆ br_ssl_engine_set_aes_ctrcbc()

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

Set the AES/CTR+CBC implementation.

Parameters
ccSSL engine context.
implAES/CTR+CBC encryption/decryption implementation (or NULL).

◆ br_ssl_engine_set_all_flags()

static void br_ssl_engine_set_all_flags ( br_ssl_engine_context cc,
uint32_t  flags 
)
inlinestatic

Set all engine behavioural flags.

Parameters
ccSSL engine context.
flagsnew 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
ccSSL engine context
iobufI/O buffer.
iobuf_lenI/O buffer length (in bytes).
bidinon-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
ccSSL engine context
ibufinput buffer.
ibuf_leninput buffer length (in bytes).
obufoutput buffer.
obuf_lenoutput buffer length (in bytes).

◆ br_ssl_engine_set_cbc()

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

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

Parameters
ccSSL engine context.
impl_inrecord CBC decryption implementation (or NULL).
impl_outrecord CBC encryption implementation (or NULL).

◆ br_ssl_engine_set_ccm()

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

Set the record encryption and decryption engines for CCM.

Parameters
ccSSL engine context.
impl_inrecord CCM decryption implementation (or NULL).
impl_outrecord CCM encryption implementation (or NULL).

◆ br_ssl_engine_set_chacha20()

static void br_ssl_engine_set_chacha20 ( br_ssl_engine_context cc,
br_chacha20_run  ichacha 
)
inlinestatic

Set the ChaCha20 implementation.

Parameters
ccSSL engine context.
ichachaChaCha20 implementation (or NULL).

◆ br_ssl_engine_set_chapol()

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

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

Parameters
ccSSL engine context.
impl_inrecord ChaCha20 decryption implementation (or NULL).
impl_outrecord 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
ccSSL 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
ccSSL 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
ccSSL 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
ccSSL 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
ccSSL 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
ccSSL 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
ccSSL 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
ccSSL engine context.

◆ br_ssl_engine_set_des_cbc()

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

Set the DES/CBC implementations.

Parameters
ccSSL engine context.
impl_encDES/CBC encryption implementation (or NULL).
impl_decDES/CBC decryption implementation (or NULL).

◆ br_ssl_engine_set_ec()

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

Set the EC implementation.

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

Parameters
ccSSL engine context.
iecEC implementation (or NULL).

◆ br_ssl_engine_set_ecdsa()

static void br_ssl_engine_set_ecdsa ( br_ssl_engine_context cc,
br_ecdsa_vrfy  iecdsa 
)
inlinestatic

◆ br_ssl_engine_set_gcm()

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

Set the record encryption and decryption engines for GCM.

Parameters
ccSSL engine context.
impl_inrecord GCM decryption implementation (or NULL).
impl_outrecord GCM encryption implementation (or NULL).

◆ br_ssl_engine_set_ghash()

static void br_ssl_engine_set_ghash ( br_ssl_engine_context cc,
br_ghash  impl 
)
inlinestatic

Set the GHASH implementation (used in GCM mode).

Parameters
ccSSL engine context.
implGHASH implementation (or NULL).

◆ br_ssl_engine_set_hash()

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

Set a hash function implementation (by ID).

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

Parameters
ctxSSL engine context.
idhash function identifier.
implhash function implementation (or NULL).

◆ br_ssl_engine_set_poly1305()

static void br_ssl_engine_set_poly1305 ( br_ssl_engine_context cc,
br_poly1305_run  ipoly 
)
inlinestatic

Set the Poly1305 implementation.

Parameters
ccSSL engine context.
ipolyPoly1305 implementation (or NULL).

◆ br_ssl_engine_set_prf10()

static void br_ssl_engine_set_prf10 ( br_ssl_engine_context cc,
br_tls_prf_impl  impl 
)
inlinestatic

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

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

Parameters
ccSSL engine context.
implPRF implementation (or NULL).

◆ br_ssl_engine_set_prf_sha256()

static void br_ssl_engine_set_prf_sha256 ( br_ssl_engine_context cc,
br_tls_prf_impl  impl 
)
inlinestatic

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

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

Parameters
ccSSL engine context.
implPRF implementation (or NULL).

◆ br_ssl_engine_set_prf_sha384()

static void br_ssl_engine_set_prf_sha384 ( br_ssl_engine_context cc,
br_tls_prf_impl  impl 
)
inlinestatic

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

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

Parameters
ccSSL engine context.
implPRF implementation (or NULL).

◆ br_ssl_engine_set_protocol_names()

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

Set the supported protocol names.

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

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

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

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

Parameters
ctxSSL engine context.
nameslist of protocol names (zero-terminated).
numnumber of protocol names (MUST be 1 or more).

◆ br_ssl_engine_set_rsavrfy()

static void br_ssl_engine_set_rsavrfy ( br_ssl_engine_context cc,
br_rsa_pkcs1_vrfy  irsavrfy 
)
inlinestatic

Set the RSA signature verification implementation.

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

Parameters
ccSSL engine context.
irsavrfyRSA signature verification implementation.

◆ br_ssl_engine_set_session_parameters()

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

Set the session parameters to the provided values.

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

Parameters
ccSSL engine context.
ppsource 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
ccSSL engine context.
suitescipher suites.
suites_numnumber of cipher suites.

◆ br_ssl_engine_set_versions()

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

Set the minimum and maximum supported protocol versions.

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

Parameters
ccSSL engine context.
version_minminimum supported TLS version.
version_maxmaximum supported TLS version.

◆ br_ssl_engine_set_x509()

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

Set the X.509 engine.

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

Parameters
ccSSL engine context.
x509ctxX.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
ccSSL engine context.
dstdestination buffer for exported key.
lenexported key length (in bytes).
labeldisambiguation label.
contextcontext value (or NULL).
context_lencontext length (in bytes).
Returns
1 on success, 0 on error.

◆ br_ssl_server_get_client_curves()

static uint32_t br_ssl_server_get_client_curves ( const br_ssl_server_context *  cc)
inlinestatic

Get the elliptic curves supported by the client.

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

Parameters
ccserver context.
Returns
the client-supported elliptic curves.

◆ br_ssl_server_get_client_hashes()

static uint32_t br_ssl_server_get_client_hashes ( const br_ssl_server_context *  cc)
inlinestatic

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

This value is a bit field:

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

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

Parameters
ccserver context.
Returns
the client-supported hash functions and signature algorithms.

◆ br_ssl_server_get_client_suites()

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

Get the supported client suites.

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

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

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

Parameters
ccserver context.
numreceives 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
ccserver context to initialise.
chainserver certificate chain.
chain_lenchain length (number of certificates).
cert_issuer_key_typecertificate issuer's key type.
skEC 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
ccserver context to initialise.
chainserver certificate chain.
chain_lencertificate chain length (number of certificate).
skRSA 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
ccserver context to initialise.
chainserver certificate chain.
chain_lencertificate chain length (number of certificate).
skRSA 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
ccserver context to initialise.
chainserver certificate chain.
chain_lencertificate chain length (number of certificate).
skRSA 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
ccserver context to initialise.
chainserver certificate chain.
chain_lencertificate chain length (number of certificate).
skEC 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
ccserver context to initialise.
chainserver certificate chain.
chain_lencertificate chain length (number of certificate).
skEC 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
ccserver context to initialise.
chainserver certificate chain.
chain_lencertificate chain length (number of certificate).
skRSA 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
ccserver context to initialise.
chainserver certificate chain.
chain_lencertificate chain length (number of certificate).
skEC 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
ccserver context to initialise.
chainserver certificate chain.
chain_lencertificate chain length (number of certificate).
skEC 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
ccserver context.
Returns
1 on success, 0 on error.

◆ br_ssl_server_set_cache()

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

Configure the cache for session parameters.

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

Parameters
ccserver context.
vtablesession cache context.

◆ br_ssl_server_set_policy()

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

Set an externally provided policy context.

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

Parameters
ccserver context.
pctxpolicy 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
ccserver context.
chainserver certificate chain to send.
chain_lenchain length (number of certificates).
skserver private key (EC).
allowed_usagesallowed private key usages.
cert_issuer_key_typeissuing CA's key type.
iecEC core implementation.
iecdsaECDSA 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
ccserver context.
chainserver certificate chain to send to the client.
chain_lenchain length (number of certificates).
skserver private key (RSA).
allowed_usagesallowed private key usages.
irsacoreRSA core implementation.
irsasignRSA signature implementation (PKCS#1 v1.5).

◆ br_ssl_server_set_trust_anchor_names()

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

Activate client certificate authentication.

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

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

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

Parameters
ccserver context.
ta_namesencoded trust anchor names.
numnumber of encoded trust anchor names.

◆ br_ssl_server_set_trust_anchor_names_alt()

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

Activate client certificate authentication.

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

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

Parameters
ccserver context.
tastrust anchors (only names are used).
numnumber 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
ccserver 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
ccsession cache context.
idsession 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
ccsession cache context.
storestorage space for cached entries.
store_lenstorage 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
ccSSL 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
ccSSL 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
ctxwrapper context to initialise.
engineSSL engine to wrap.
low_readcallback for reading data from the transport.
read_contextcontext pointer for low_read().
low_writecallback for writing data on the transport.
write_contextcontext 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
ccSSL wrapper context.
dstdestination buffer for application data.
lenmaximum 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
ccSSL wrapper context.
dstdestination buffer for application data.
lennumber 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
ccSSL wrapper context.
srcsource buffer for application data.
lenmaximum 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
ccSSL wrapper context.
srcsource buffer for application data.
lennumber of bytes to write.
Returns
0 on success, or -1 on error.

Variable Documentation

◆ br_sslrec_in_cbc_vtable

const br_sslrec_in_cbc_class br_sslrec_in_cbc_vtable

Static, constant vtable for record decryption with CBC.

◆ br_sslrec_in_ccm_vtable

const br_sslrec_in_ccm_class br_sslrec_in_ccm_vtable

Static, constant vtable for record decryption with CCM.

◆ br_sslrec_in_chapol_vtable

const br_sslrec_in_chapol_class br_sslrec_in_chapol_vtable

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

◆ br_sslrec_in_gcm_vtable

const br_sslrec_in_gcm_class br_sslrec_in_gcm_vtable

Static, constant vtable for record decryption with GCM.

◆ br_sslrec_out_cbc_vtable

const br_sslrec_out_cbc_class br_sslrec_out_cbc_vtable

Static, constant vtable for record encryption with CBC.

◆ br_sslrec_out_ccm_vtable

const br_sslrec_out_ccm_class br_sslrec_out_ccm_vtable

Static, constant vtable for record encryption with CCM.

◆ br_sslrec_out_chapol_vtable

const br_sslrec_out_chapol_class br_sslrec_out_chapol_vtable

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

◆ br_sslrec_out_clear_vtable

const br_sslrec_out_class br_sslrec_out_clear_vtable

Static, constant vtable for the no-encryption engine.

◆ br_sslrec_out_gcm_vtable

const br_sslrec_out_gcm_class br_sslrec_out_gcm_vtable

Static, constant vtable for record encryption with GCM.