TLS

tls name

yaml type: host

DNS name or IP address used for server-certificate verification. If not set, the corresponding upstream address is used.

This value uses the same parser as host, so both IDNA domain names and literal IP addresses are accepted.

tls version

yaml type: str | float

TLS version to use.

String matching is case-insensitive. Common aliases such as tls10, tls1_0, and 1.0 are accepted. Floating-point values 1.0 through 1.3 are also accepted.

tls ticketer

yaml type: map

Rolling TLS ticketer supporting:

  • generation of new encryption keys

  • update and expiration checks for old decryption keys

  • synchronization of keys from a remote source

The supported fields are:

  • check_interval

    optional, type: humanize duration

    Set the check interval for key expiration. It will also try to fetch keys from remote source.

    If the encryption key is expired with it’s lifetime, and no new key is fetched from remote source, a new random key will be generated locally.

    default: 5min

  • local_lifetime

    optional, type: u32

    Set the lifetime value (in seconds) for local generated key. The expire time will be half of this lifetime value.

    default: 12 * 3600

  • source

    optional, type: tls ticket remote source

    Remote source used to fetch TLS ticket keys.

    default: not set

tls ticket remote source

yaml type: map

Configuration for the remote source used to fetch TLS ticket keys.

Multiple source types may be available. The type configuration key selects the source type.

Key Format

encrypt key

json type: map

The config keys are:

  • name

    required, type: hex str

    Set the name, which should be of 16 bytes.

  • aes

    required, type: hex str

    Set the AES KEY, which should be of 32 bytes.

  • hmac

    required, type: hex str

    Set the HMAC KEY, which should be of 16 bytes.

  • lifetime

    optional, type: u32

    Set the lifetime value.

    default: 24 * 3600

decrypt key

json type: map

The config keys are:

  • name

    required, type: hex str

    Set the name, which should be of 16 bytes.

  • aes

    required, type: hex str

    Set the AES KEY, which should be of 32 bytes.

  • hmac

    required, type: hex str

    Set the HMAC KEY, which should be of 16 bytes.

  • expire

    required, type: rfc3339 datetime str

    Set the expire datetime.

Source Types

redis

yaml type: map

A redis TLS ticket key source.

The following keys are supported:

tls certificates

yaml type: file | seq

Certificate file or files in PEM format (see openssl-req(1)).

If relative, it will be searched in the directory that contains current config file.

The loader also accepts inline PEM text as a YAML string whose first non-whitespace characters start with --.

tls private_key

yaml type: file

Private-key file in PKCS#8 (see openssl-genpkey(1)) or traditional PEM format.

If relative, it will be searched in the directory that contains current config file. The last one in the file will be used if many keys are found.

Inline PEM text is also accepted when the YAML string starts with -- after leading whitespace.

tls cert pair

yaml value: map

Pair of TLS certificate material and private key.

The keys are:

  • certificate

    required, type: tls certificates

    Set client certificates if client auth is needed by remote server. Private key must also be set if client auth is needed.

    default: not set

  • private_key

    required, type: tls private_key

    Set the private key for client if client auth is needed by remote server. Client certificates are also needed if client auth is needed.

Aliases:

  • cert for certificate

  • key for private_key

tlcp cert pair

yaml value: map

Pair of TLCP certificate material and private key.

The keys are:

  • sign_certificate

    required, type: tls certificates

    Set client sign certificates if client auth is needed by remote server. Private key must also be set if client auth is needed.

    default: not set

  • sign_private_key

    required, type: tls private_key

    Set the sign private key for client if client auth is needed by remote server. Client certificates are also needed if client auth is needed.

    default: not set

  • enc_certificate

    required, type: tls certificates

    Set client enc certificates if client auth is needed by remote server. Private key must also be set if client auth is needed.

    default: not set

  • enc_private_key

    required, type: tls private_key

    Set the enc private key for client if client auth is needed by remote server. Client certificates are also needed if client auth is needed.

Aliases:

  • sign_cert for sign_certificate

  • sign_key for sign_private_key

  • enc_cert for enc_certificate

  • enc_key for enc_private_key

Example:

cert_pair:
  cert: client.crt
  key: client.key

openssl protocol

yaml value: string

Set openssl protocol version.

Current supported values are:

  • tls1.0

  • tls1.1

  • tls1.2

  • tls1.3

  • tlcp (only if vendored-tongsuo feature is enabled)

openssl ciphers

yaml value: string or seq

Set openssl cipher list or ciphersuites for the specified protocol.

Values can be obtained from openssl ciphers -v command.

For string value, it can be ciphers joined by ‘:’.

For seq value, each one should be a cipher string.

openssl tls client config

yaml value: map

The tls config to be used as a tls client.

The map is consists of the following fields:

  • protocol

    optional, type: openssl protocol

    Set to use a specific protocol version.

    default: not set

  • min_tls_version

    optional, type: tls version

    Set the minimal TLS version to use if protocol is not set.

    default: not set

  • max_tls_version

    optional, type: tls version

    Set the maximum TLS version to use if protocol is not set.

    default: not set

  • ciphers

    optional, type: openssl ciphers require: protocol

    Set to use a specific set of ciphers for the specified protocol version.

    default: not set

  • disable_sni

    optional, type: bool

    Whether to send the Server Name Indication (SNI) extension during the client handshake.

    default: false

  • cert_pair

    optional, type: tls cert pair, conflict: certificate, private_key

    Set the client certificate and private key pair.

    default: not set

  • tlcp_cert_pair

    optional, type: tlcp cert pair

    Set the client certificate and private key pair for TLCP protocol. This will be in effect only if protocol is set to tlcp.

    default: not set

  • certificate

    optional, type: tls certificates, conflict: cert_pair

    Set client certificates if client auth is needed by remote server. Private key must also be set if client auth is needed.

    default: not set

  • private_key

    optional, type: tls private_key, conflict: cert_pair

    Set the private key for client if client auth is needed by remote server. Client certificates are also needed if client auth is needed.

    default: not set

  • ca_certificate | server_auth_certificate

    optional, type: tls certificates

    A list of certificates for server auth. If not set, the system default ca certificates will be used.

    default: not set

  • no_default_ca_certificate

    optional, type: bool

    Set if you don’t want to load default ca certificates.

    default: false

  • handshake_timeout

    optional, type: humanize duration

    Set the tls handshake timeout value.

    default: 10s

  • no_session_cache

    optional, type: bool

    Set if you want to disable cache of TLS sessions.

    default: false

  • use_builtin_session_cache

    optional, type: bool

    Set if we should use OpenSSL builtin session cache.

    default: false

  • session_cache_lru_max_sites

    optional, type: usize

    Set how many LRU sites should have cached sessions.

    Only in use if this tls client is used by many sites.

    default: 128

  • session_cache_each_capacity

    optional, type: usize

    Set how many sessions should be kept for each site.

    default: 16

  • key_exchange_groups | supported_groups

    optional, type: str

    Set the supported key exchange groups.

    default: not set

  • use_ocsp_stapling

    optional, type: bool

    Set this to true to request a stapled OCSP response from the server.

    Verify of this response is still not implemented.

    default: not set, the default value may vary between different OpenSSL variants

  • enable_sct

    optional, type: bool

    Enable the processing of signed certificate timestamps (SCTs) for OpenSSL, or enables SCT requests for BoringSSL.

    Verify of this response is still not implemented for BoringSSL variants.

    default: not set, the default value may vary between different OpenSSL variants

  • enable_grease

    optional, type: bool

    Enable GREASE. See RFC 8701.

    default: not set, the default value may vary between different OpenSSL variants

  • permute_extensions

    optional, type: bool

    Whether to permute TLS extensions.

    default: not set, the default value may vary between different OpenSSL variants

  • insecure:

    optional, type: bool

    DANGEROUS: Enable to not verify peer (server) tls certificates.

    When this option is enabled, verify errors will be logged to the configured structured logger.

    default: false

openssl server config

yaml value: map

The tls config to be used as a openssl tls server.

The map is consists of the following fields:

  • cert_pairs

    optional, type: tls cert pair or seq

    Set certificate and private key pairs for this TLS server.

    If not set, TLS protocol will be disabled.

    default: not set

  • tlcp_cert_pairs

    optional, type: tlcp cert pair or seq

    Set certificate and private key pairs for this TLCP server.

    If not set, TLCP protocol will be disabled.

    default: not set

  • enable_client_auth

    optional, type: bool

    Set if you want to enable client auth.

    default: disabled

  • session_id_context

    optional, type: str

    A string that will be added to the prefix when calculate the session id context sha1 hash.

    default: not set

  • no_session_ticket

    optional, type: bool

    Set if we should disable TLS session ticket (stateless session resumption by Session Ticket).

    default: false

  • no_session_cache

    optional, type: bool

    Set if we should disable TLS session cache (stateful session resumption by Session ID).

    default: false

  • ca_certificate | client_auth_certificate

    optional, type: tls certificates

    A list of certificates for client auth. If not set, the system default ca certificates will be used.

    default: not set

  • handshake_timeout

    optional, type: humanize duration

    Set the tls handshake timeout value.

    default: 10s

rustls client config

yaml value: map

The tls config to be used as a tls client.

The map is consists of the following fields:

  • no_session_cache

    optional, type: bool

    Set if you want to disable cache of TLS sessions.

    default: false

  • disable_sni

    optional, type: bool

    Whether to send the Server Name Indication (SNI) extension during the client handshake.

    default: false

  • max_fragment_size

    optional, type: usize

    Set the maximum size of TLS message we’ll emit.

    default: default value in tls driver

  • cert_pair

    optional, type: tls cert pair, conflict: certificate, private_key

    Set the client certificate and private key pair.

    default: not set

  • certificate

    optional, type: tls certificates

    Set client certificates if client auth is needed by remote server. Private key must also be set if client auth is needed.

    default: not set

  • private_key

    optional, type: tls private_key

    Set the private key for client if client auth is needed by remote server. Client certificates are also needed if client auth is needed.

    default: not set

  • ca_certificate | server_auth_certificate

    optional, type: tls certificates

    A list of certificates for server auth. If not set, the system default ca certificates will be used.

    default: not set

  • no_default_ca_certificate

    optional, type: bool

    Set if you don’t want to load default ca certificates.

    default: false

  • use_builtin_ca_certificate

    optional, type: bool

    Set to true if you want to use built in webpki-roots ca certificates as default ca certificates.

    default: false

  • handshake_timeout

    optional, type: humanize duration

    Set the tls handshake timeout value.

    default: 10s

rustls server config

yaml value: map

The tls config to be used as a tls server.

The map is consists of the following fields:

  • cert_pairs

    optional, type: tls cert pair or seq

    Set certificate and private key pairs for this TLS server.

    Note

    At least set this or certificate & private_key.

  • certificate

    optional, type: tls certificates

    Set the certificates for this TLS server.

    Note

    At least set this or cert_pairs

  • private_key

    optional, type: tls private_key

    Set the private key for this TLS server.

    Note

    At least set this or cert_pairs

  • enable_client_auth

    optional, type: bool

    Set if you want to enable client auth.

    default: disabled

  • no_session_ticket

    optional, type: bool

    Set if we should disable TLS session ticket (stateless session resumption by Session Ticket).

    default: false

  • no_session_cache

    optional, type: bool

    Set if we should disable TLS session cache (stateful session resumption by Session ID).

    default: false

  • ca_certificate | client_auth_certificate

    optional, type: tls certificates

    A list of certificates for client auth. If not set, the system default ca certificates will be used.

    default: not set

  • handshake_timeout

    optional, type: humanize duration

    Set the tls handshake timeout value.

    default: 10s