Tls_Config

Fields

certificate_chain_pem: string

Server (and, for a client that must prove who it is, client): the certificate chain as PEM, the endpoint's own certificate first, and its private key: PEM or DER (PKCS#8, PKCS#1 or SEC1; the name _pem is kept from when only PEM was read). private_key_password decrypts an encrypted PKCS#8 key (PBES2 with PBKDF2 and AES or 3DES) or an OpenSSL-style encrypted PEM one; empty for a key that is not encrypted.

private_key_pem: string

private_key_password: string

roots_pem: string

The certificate authorities to trust, as PEM (any number of certificates). Empty: the system's (see docs/extensions/tls.md for where each OS keeps them). They must be authorities: the server's own certificate listed here does not make a client trust it unless it is self-signed (the usual rule), so a certificate that a CA signed is trusted by giving that CA, or an intermediate (see root_must_be_self_signed).

crl_pem: string

Client with roots_pem: certificate revocation lists as PEM (any number, or one DER). The server's certificate must be covered: if no list in here was issued by its issuer, or one lists the certificate, the connection fails. Lists for the other certificates of a chain are used when present.

alpn: [] string

The protocols to offer (client) or accept (server) through ALPN, most preferred first: .["h2", "http/1.1"]. Empty: no ALPN extension. A server that has a list and a client that offers protocols but none in common fails the handshake.

verify: := true

Client: check the server's certificate chain and name. Turning it off makes the connection open to anyone in the middle; it exists for tests and for talking to devices on a private network, and is never the default.

verify_name: := true

Client: check that the server's certificate is for the name tls_connect is given. Off, the chain is still checked, and the name is still sent as SNI. For callers that match the name by their own rules (a database's, say); with verify_proc or the system's verifier on macOS and Windows the name is simply not passed on.

root_must_be_self_signed: := false

Client with roots_pem: the chain must end in a self-signed certificate from roots_pem. Otherwise any certificate listed there is a trust anchor, intermediate CAs included (the library's rule); OpenSSL-based clients need the root, and this option gives that behaviour.

client_auth: := false

Server: ask the client for a certificate and check it against roots_pem (or the system's roots on Linux). Clients without a valid certificate fail the handshake.

min_version: := Tls_Version.TLS_1_2

max_version: := Tls_Version.TLS_1_3

verify_proc: Tls_Verify_Proc

Replaces mbedTLS's check of the peer's chain (roots_pem and the system roots are then not used for verification). The system verifiers of macOS and Windows are this mechanism too.

verify_data: *void

key_log_proc: Tls_Key_Log_Proc

Client: called with each secret a handshake derives, as a key log line that tools such as Wireshark read to decrypt a capture. For debugging only: the lines decrypt the connection.

key_log_data: *void

native: *Tls_Native

Set by tls_config_init (its type is internal to the module): do not touch it, and do not copy a config after that.