HTTPS configuration

These Liberator configuration items define how Liberator handles secure HTTPS connections with clients.

Like Liberator’s HTTP interface, Liberator’s HTTPS interface is used to serve RTTP streaming traffic (see StreamLink connection types) and web pages from Liberator’s htdocs directory.

To enable HTTPS (and disable HTTP) in Liberator, see Enabling HTTPS.

add-virtual-host

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:

add-virtual-host
   name               [string]
   addr               [string]
   https-certificate  [string]
   https-passwordfile [string]
   https-privatekey   [string]
   https-dhparams     [string]
   wwwroot            [string]
end-virtual-host
Options for add-virtual-host
Options Type Default Description

addr

string

[none]

The IP address or hostname of this virtual host.

https-certificate

string

Value of https-certificate

The filename and directory path of the SSL (secure sockets layer) certificate used for HTTPS connections to this virtual host. The file must be in PEM format. The directory path is optional and can be in relative or absolute format.

This option overrides for this virtual host the certificate filename and path defined in the global configuration item https-certificate.

https-passwordfile

string

Value of https-passwordfile

The filename and directory path of the file containing the SSL certificate passphrase used for HTTPS connections to this virtual host. The file must be in PEM format. The directory path is optional and can be in relative or absolute format.

This option overrides for this virtual host the password filename and path defined in the global configuration item https-passwordfile.

https-privatekey

string

Value of https-privatekey

The filename and directory path of the SSL (secure sockets layer) private key used for HTTPS connections to this virtual host. The file must be in PEM format. The directory path is optional and can be in relative or absolute format.

This option overrides for this virtual host the private key filename and path defined in the global configuration item https-privatekey.

https-dhparams

string

[none]

The path to a Diffie-Hellman (DH) parameters file, which is required by ephemeral Diffie-Hellman ciphers (DHE). For instructions on how to generate a DH parameters file, see Additional requirements ephemeral Diffie-Hellman ciphers.

This option overrides for this virtual host the path to the DH parameters file defined in the global configuration item https-dhparams.

name

string

Value of the addr option

A name for this virtual host.

wwwroot

string

Value of http-wwwroot

The root directory of the Liberator’s HTML files for this virtual host. The directory path can contain the parameter %r, which is replaced at run time by the root directory (application-root) under which the Liberator runs.

This option overrides for this virtual host the root directory defined in the global configuration item http-wwwroot.

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.

# TLS certificate for host2.example.com
add-virtual-host
    addr                host2.example.com
    https-certificate   ${SSLCERT_PATH}/host2.example.com.cert.pem
    https-privatekey    ${SSLCERT_PATH}/host2.example.com.key.pem
    https-passwordfile  ${SSLCERT_PATH}/host2.example.com.key.pwd
end-virtual-host

# TLS certificate for host3.example.com
add-virtual-host
    addr                host3.example.com
    https-certificate   ${SSLCERT_PATH}/host3.example.com.cert.pem
    https-privatekey    ${SSLCERT_PATH}/host3.example.com.key.pem
    https-passwordfile  ${SSLCERT_PATH}/host3.example.com.key.pwd
end-virtual-host

https-certificate

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-cipher-list

https-cipher-list configures the SSL/TLS ciphers supported by Liberator’s HTTPS interface.

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

Review the values for https-cipher-list, https-ssl-options, and https-dhparams for compliance with your security policy before deploying Liberator to production.

For detailed information on how to set SSL/TLS protocols and ciphers for Liberator’s HTTPS interface, see Configuring support for SSL/TLS protocols and ciphers.

Syntax: https-cipher-list <openssl-cipher-list>

Type: string

Default value:

  • Liberator 6: DEFAULT

  • Liberator 7: DEFAULT:!RC4-SHA:!RC4-MD5:!DES-CBC3-SHA

https-dhparams

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).

Review the values for https-cipher-list, https-ssl-options, and https-dhparams for compliance with your security policy before deploying Liberator to production.

For instructions on how to generate a DH parameters file, see Additional requirements for ciphers that provide forward secrecy.

Availability: Liberator 6.2.14+, Liberator 7.0.1+

Syntax: https-dhparams <filepath>

Type: string

Default value: <empty string>

Example:

directssl-dhparams ${SSLCERT_PATH}/rttpd-dhparam-2048.pem

https-disable-renegotiation

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

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

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.

Wildcard support
Configuration Liberator 6.2 Liberator 7.0

https-interface

Default. A single IPv4 server socket that listens on all IPv4 interface addresses.

Default. A single IPv6 server socket that accepts IPv4-mapped addresses and that listens on all IPv6 and IPv4 interface addresses.

https-interface *

A single IPv4 server socket that listens on all IPv4 interface addresses.

A single IPv6 server socket that accepts IPv4-mapped addresses and that listens on all IPv6 and IPv4 interface addresses.

https-interface 0.0.0.0

A single IPv4 server socket that listens on all IPv4 interface addresses.

A single IPv4 server socket that listens on all IPv4 interface addresses.

https-interface ::

Not supported

A single IPv6 server socket that listens on all IPv6 interface addresses.

https-interface 0.0.0.0 ::

Not supported

A single IPv4 server socket that listens on all IPv4 interface addresses, and a single IPv6 server socket that listens on all IPv6 interface addresses.

Supported from Liberator 7.0.2
To configure Liberator’s HTTPS server to listen on all its host’s IPv4 and IPv6 addresses, use https-interface 0.0.0.0 :: in preference to relying on the default setting. The default setting is less resilient than specifying separate IPv4 and IPv6 wild cards because IPv4-to-IPv6 address mapping can be disabled by a system administrator at the operating system level.

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

Type: array of strings

Default value: [all available network interfaces]

https-passwordfile

https-passwordfile specifies the filename and directory path of the file containing the passphrase for the encrypted SSL/TLS key used for HTTPS connections. 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.

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

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

In the Caplin Platform Deployment Framework, a configuration variable LIBERATOR${THIS_LEG}_HTTPSPORT is used to specify Liberator’s https-port. See Configuration macros and items and How can I …​ Configure how Liberator handles HTTPS connections.

Syntax: https-port <network-port>

Type: integer

Default value: 4443

https-privatekey

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

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).

Review the values for https-cipher-list, https-ssl-options, and https-dhparams for compliance with your security policy before deploying Liberator to production.

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.

Supported OpenSSL options
Option Description

SSL_OP_ALL

Enable all of OpenSSL’s workarounds for known bugs in client implementations of SSL. For the full list of workarounds enabled by this option, see SSL_CTX_set_options on the OpenSSL website.

SSL_OP_NO_SSLv2

Disable support for SSL 2.

SSL_OP_NO_SSLv3

Disable support for SSL 3.

SSL_OP_NO_TLSv1

Disable support for TLS 1.

SSL_OP_NO_TLSv1_1

Disable support for TLS 1.1. Available from Liberator 6.2.2.

SSL_OP_NO_TLSv1_2

Disable support for TLS 1.2. Available from Liberator 6.2.2.

For a detailed information on how to set SSL/TLS protocols and ciphers for Liberator’s HTTPS interface, see Configuring support for SSL/TLS protocols and ciphers.

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

Type: string

Default value:

  • Liberator 6: SSL_OP_NO_SSLv2

  • Liberator 7: SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1

ssl-random-seed

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.

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

<source> Description

builtin

Seed the PRNG from /dev/urandom on Linux or CryptGenRandom and other sources of entropy on Microsoft Windows.

Arguments path and bytes are ignored.

file

Uses the first <bytes> bytes of the data in the file <path> to seed the PRNG. If the path to the file is relative, the path is relative to the DataSource application’s root directory.

exec

Uses the first <bytes> bytes of the output from the command specified in <path> to seed the PRNG. If the path to the command is relative, the path is relative to the DataSource application’s root directory.

Type: string

Default value: builtin

Examples

  • ssl-random-seed builtin

  • ssl-random-seed file /dev/hwrng 1024


See also: