HTTPS configuration

add-virtual-host defines a name-based or IP-based virtual host. Each virtual-host definition overrides some or all of the global configuration options https-certificate, https-privatekey, https-passwordfile, https-dhparams, and http_wwwroot for a specific IP address or hostname.

Liberator supports the TLS extension Server Name Indication (SNI) for name-based virtual hosting over HTTPS. For more information on SNI, see Server Name Indication.

To configure Liberator to present a different TLS certificate for each of the alternative hostnames by which a Liberator server is known, define an add-virtual-host block for each alternative hostname.

Syntax:

Example:

In this example, a Liberator server, host1.example.com, also has DNS entries for the host names host2.example.com and host3.example.com at the same IP address. The example configuration below uses add-virtual-host blocks to define the TLS certificates to use for host1.example.com and host2.example.com.

https-certificate specifies the filename and directory path of the SSL (secure sockets layer) certificate used for HTTPS connections. This file must be in PEM format. The directory path is optional and can be in relative or absolute format.

This item is overridden for specific virtual host connections by the https-certificate option of the add-virtual-host that defines the virtual host.

For more information on setting https-certificate, see Installing keys and certificates.

The default value for https-certificate is the same as the default value for https-privatekey because both the certificate and the private key can be contained in the same file.

Syntax: https-certificate <PEM-filename-and-path>

Type: string

Default value: cert.pem

https-ciphersuites specifies the TLS 1.3 ciphers supported by Liberator’s HTTPS interface, formatted as an OpenSSL cipher list. To set the TLS 1.0–1.2 ciphers supported by Liberator, see https-cipher-list.

This is an advanced TLS 1.3 configuration option for specific use cases only. You do not need to set this option to enable TLS 1.3 support in Liberator. TLS 1.3 support is enabled by default from Liberator 7.1.5.

When https-ciphersuites is not specified, Liberator uses OpenSSL’s default TLS 1.3 cipher list.

In accordance with the TLS specification, Liberator ignores the priority order of ciphers in https-ciphersuites and favours the TLS client’s cipher priority order. To reverse this default behaviour, set the SSL_OP_CIPHER_SERVER_PREFERENCE flag in https-ssl-options. To log the cipher lists of connecting clients, see https-log-hello-ciphers.

Since: Liberator 7.1.25

Syntax: https-ciphersuites <openssl_cipher_list>

Type: string

Default value: OpenSSL default

https-cipher-list specifies the TLS 1.0–1.2 ciphers supported by Liberator’s HTTPS interface, formatted as an OpenSSL cipher list.

In accordance with the TLS specification, when choosing a cipher for a connection, Liberator chooses the client’s most preferred cipher from among the ciphers they have in common. To reverse this default behaviour, set the SSL_OP_CIPHER_SERVER_PREFERENCE flag in https-ssl-options. To define Liberator’s cipher preference, order ciphers in https-cipher-list in descending order of preference, most preferred cipher first.

To log the cipher lists of connecting TLS clients, see https-log-hello-ciphers.

Configure this item in conjunction with https-ssl-options (SSL/TLS protocol versions) and https-dhparams (required for DHE ciphers).

For detailed information on how to set ciphers for Liberator’s HTTPS interface, see Configuring supported TLS ciphers.

Syntax: https-cipher-list <openssl_cipher_list>

Type: string

Default value:

Examples: See Configuring supported TLS ciphers

https-dhparams specifies the path to a Diffie-Hellman (DH) parameters file, which is required by ephemeral Diffie-Hellman ciphers (DHE).

Configure this item in conjunction with https-ssl-options (SSL/TLS protocol versions) and https-cipher-list (SSL/TLS ciphers).

For instructions on how to generate a DH parameters file, see Generating a Diffie-Hellman parameters file for DHE ciphers.

Availability: Liberator 6.2.14+, Liberator 7.0.1+

Syntax: https-dhparams <filepath>

Type: string

Default value: <empty string>

Example:

https-disable-renegotiation when set to TRUE, prevents clients from renegotiating their HTTPS connections. This protects against Denial of Service attacks involving repeated attempts to renegotiate.

Syntax: https-disable-renegotiation <boolean>

Type: boolean

Default value: FALSE (Liberator 6.2), TRUE (Liberator 7)

https-enable switches on support for HTTPS connections when set to TRUE.

Syntax: https-enable <boolean>

Type: boolean

Default value: FALSE (HTTPS connections not supported)

https-interface specifies the network interfaces to listen on for HTTPS connection requests.

For a Liberator deployed within a Caplin Deployment Framework, https-interface is normally set indirectly by specifying a value for the Deployment Framework configuration macro LIBERATOR${THIS_LEG}_HTTPSINTERFACE. Only one HTTPS interface can be specified in the macro; to add extra interfaces, append new https-interface items to the configuration override file <Framework-root>/global_config/overrides/servers/Liberator/etc/rttpd.conf.

This configuration item supports IPv6 addresses from version 7 of Liberator, and multiple address wildcards from version 7.0.2.

Syntax: https-interface <ip-address> …​

Type: array of strings

Default value: [all available network interfaces]

Enables logging of the cipher list presented by TLS clients in the TLS handshake with Liberator.

From Liberator 7.1.25, client cipher lists are logged at INFO level and require the SSL.Detail log category to be enabled (see log-category-filter):

For Liberator 7.1.23 and 7.1.24, client cipher lists for successful connections are logged at DEBUG level. Client cipher lists for unsuccessful connections are logged at INFO level.

Since: Liberator 7.1.23

Syntax: https-log-hello-ciphers <boolean>

Type: boolean

Default value: FALSE

https-passwordfile specifies the filename and directory path of the file containing the passphrase for the encrypted SSL/TLS key used for HTTPS connections (see https-privatekey). The directory path is optional and can be in relative or absolute format.

This item is overridden for specific virtual host connections by the https-passwordfile option of the add-virtual-host that defines the virtual host.

If the TLS key is unencrypted, then the password file must be empty.

From Liberator 7.1.9: If the TLS key is unencrypted and you don’t want to deploy an empty password file, then set the configuration variable HTTPS_PASSWORD_FILE_REQUIRED to NO in the Deployment Framework file global_config/environment.conf.

For more information on setting http-passwordfile, see Installing keys and certificates.

Syntax: https-passwordfile <password-filename-and-path>

Type: string

Default value: rttpd_https.pwd

https-port specifies the network port that Liberator listens on for HTTPS connection requests.

Syntax: https-port <network-port>

Type: integer

Default value: 4443

https-privatekey specifies the filename and directory path of the SSL (secure sockets layer) private key used for HTTPS connections. This file must be in PEM format. The directory path is optional and can be in relative or absolute format.

This item is overridden for specific virtual host connections by the https-privatekey option of the add-virtual-host that defines the virtual host.

For information on setting the private key, see Installing keys and certificates.

The default value of https-privatekey is the same as the default for https-certificate because both the certificate and the private key can be contained in the same file.

Syntax: https-privatekey <private-key-filename-and-path>

Type: string

Default value: cert.pem

https-ssl-options configures the SSL/TLS protocols accepted by Liberator’s HTTPS interface.

Configure this item in conjunction with https-cipher-list (SSL/TLS ciphers) and https-dhparams (required for DHE ciphers).

Use https-ssl-options to disable support for older versions of SSL, and to enable workarounds for known bugs in client implementations of SSL.

This configuration item takes one parameter: a pipe-separated list of OpenSSL options from the table below.

For more information on setting TLS protocol versions for Liberator’s HTTPS interface, see Configuring supported TLS protocol versions.

Syntax: https-ssl-options <option>[|<option>]…​

Type: string

Default value:

Examples: See Configuring supported TLS protocol versions.

ssl-random-seed overrides OpenSSL’s automatic seeding of its pseudo random number generator (PRNG) by providing an explicit source of random data with which to seed the PRNG.

On Linux, the OpenSSL PRNG is automatically seeded from the non-blocking device file /dev/urandom. On Microsoft Windows, the PRNG is automatically seeded from CryptGenRandom and other sources of entropy. Source: Random Numbers: Seeds on the OpenSSL Wiki.

If the standard sources of entropy used to automatically seed OpenSSL’s PRNG do not comply with your organisation’s security policy, ssl-random-seed provides you with the flexibility to seed OpenSSL’s PRNG with a specific source of entropy.

The source of entropy can be a file or the output of a command. You can optionally specify the number of bytes to read in.

For more information, see DataSource: Seed the OpenSSL random number generator.

Syntax: ssl-random-seed <source> [<path>] [<bytes>]

Type: string

Default value: builtin

Examples

See also: