# HTTPS configuration

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

The Secure Sockets Layer (SSL) is a commonly-used protocol for managing the security of message transmission on the Internet, and offers a greater level of protection than standard HTTP transmission. Web pages and other standard HTTP traffic can be sent over HTTPS.

Liberator can run as an HTTPS web server like most commonly available web servers. When it’s configured to use HTTPS, all RTTP data is sent over an HTTPS connection too, which means your streaming data and trade transactions are secure. Liberator supports standard SSL server-side certificates to authenticate the server to the client. The certificates must be generated and signed by a certificate authority.

To enable HTTPS in Liberator, see Configure how Liberator handles HTTPS connections.

`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]
https-certificate  [string]
https-privatekey   [string]
https-dhparams     [string]
wwwroot            [string]
end-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

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 Diffe-Hellman (DH) parameters file, which is required by the ephemeral Diffie-Hellman ciphers DHE and ECDHE. 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

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

Liberator ships with a demonstration (self-signed) SSL certificate file, `rttpd_https.pem`. In versions of the Deployment Framework prior to 7.0.2, this certificate is automatically copied to the directory `global_config/ssl` if no certificate of the same name is found there. From version 7.0.2 of the Deployment Framework, you must explicitly run the `./dfw copy-ssl-demo-files` command if you want to use the demonstration certificate in development and testing.

 Do not use the `rttpd_https.pem` certificate that ships with Liberator in production systems.

In the Caplin Platform Deployment Framework, a configuration macro `SSLCERT_PATH` is used to specify the directory path in the Liberator’s `https-certificate` setting. See Configuration macros and items.

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` specifies a colon-separated list of cipher strings. These cipher strings select, in preferred order, the various SSL ciphers (cryptographic algorithms) that Liberator can use for its HTTPS connections. The ciphers are selected from the set available in the version of OpenSSL built into Liberator.

The format of the cipher list is as defined for the `cipherlist` argument of the OpenSSL `ciphers` tool; for details see the OpenSSL ciphers(1) manual page, which includes a list of the available cipher suite names. At run time, Liberator passes the cipher list as a control string to the OpenSSL function `SSL_CTX_set_cipher_list()`; this function uses the control string to set up the list of available SSL ciphers.

You should regularly review your cipher list under guidance from security professionals.

 By default, Liberator 7 supports only TLS 1.1 and TLS 1.2; all other SSL/TLS versions are disabled. This is not compatible with older versions of Internet Explorer (8, 9, and 10), which by default disable TLS 1.1 and TLS 1.2. TLS 1.0 is considered insecure. If you have customers with older versions of Internet Explorer, we recommend that you encourage them to upgrade. However, if you want to re-enable support for TLS 1.0 in Liberator 7, follow the steps below: In the file `global_config/overrides/servers/Liberator/etc/rttpd.conf`, override the value of https-ssl-options to disable only SSLv2 and SSLv3: `https-ssl-options SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3` In the file `global_config/overrides/servers/Liberator/etc/rttpd.conf`, override the value of https-cipher-list to include ciphers from the TLS 1.0 cipher suite and higher. See the OWASP Cipher String Cheat Sheet and the Mozilla Security/Server Side TLS wiki page for guidance.

Syntax: `https-cipher-list <cipher>:<cipher>:<cipher>…​`

Type: string

Default value (Liberator 6): `DEFAULT`

Default value (Liberator 7): `DEFAULT:!RC4-SHA:!RC4-MD5:!DES-CBC3-SHA`

Example:

`https-cipher-list HIGH+TLSv1.2:!RC4:!DES:!3DES:!MD5:!aNULL:!eNULL:!NULL`

The above cipher string selects all ciphers that are considered high in strength and in the TLS 1.2 cipher suite, and then removes all RC4, DES, 3DES, MD5, and NULL ciphers from the resulting set.

## https-dhparams

`https-dhparams` specifies the path to a Diffie-Hellman (DH) parameters file, which is required by the ephemeral Diffie-Helmann cipher suites (DHE and ECDHE), which provide forward secrecy.

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 wildcards because IPv4-to-IPv6 address mapping can be disabled by a system administrator at the operating system level.

Syntax: `https-interface <space-separated-list-of-interface-ip-addresses>`

Type: array of strings

Default value: [all available network interfaces]

`https-passwordfile` specifies the filename and directory path of the file containing the SSL certificate passphrase 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.

Liberator ships with a demonstration password file, `rttpd_https.pwd`. In versions of the Deployment Framework prior to 7.0.2, this file is automatically copied to the directory `global_config/ssl` if no file of the same name is found there. From version 7.0.2 of the Deployment Framework, you must explicitly run the `./dfw copy-ssl-demo-files` command if you want to use the demonstration SSL credentials in development and testing.

 Do not use the `rttpd_https.pwd` file that ships with Liberator in production systems.

In the Caplin Platform Deployment Framework, a configuration macro `SSLCERT_PATH` is used to specify the directory path in the Liberator’s `https-passwordfile` setting. See Configuration macros and items.

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 macro `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 and for direct 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.

Liberator ships with a demonstration private key file, `rttpd_https.key`. In versions of the Deployment Framework prior to 7.0.2, this file is automatically copied to the directory `global_config/ssl` if no file of the same name is found there. From version 7.0.2 of the Deployment Framework, you must explicitly run the `./dfw copy-ssl-demo-files` command if you want to use the demonstration SSL credentials in development and testing.

 Do not use the `rttpd_https.key` file that ships with Liberator in production systems.

In the Caplin Platform Deployment Framework, a configuration macro `SSLCERT_PATH` is used to specify the directory path in the Liberator’s `https-privatekey` setting. See Configuration macros and items.

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` changes the protocols accepted by the OpenSSL library packaged with Liberator. Use `https-ssl-options` to disable support for older versions of SSL, and to enable workarounds for known bugs in client implementations of SSL.

 By default, Liberator 7 supports only TLS 1.1 and TLS 1.2; all other SSL/TLS versions are disabled. This is not compatible with older versions of Internet Explorer (8, 9, and 10), which by default disable TLS 1.1 and TLS 1.2. TLS 1.0 is considered insecure. If you have customers with older versions of Internet Explorer, we recommend that you encourage them to upgrade. However, if you want to re-enable support for TLS 1.0 in Liberator 7, follow the steps below: In the file `global_config/overrides/servers/Liberator/etc/rttpd.conf`, override the value of https-ssl-options to disable only SSLv2 and SSLv3: `https-ssl-options SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3` In the file `global_config/overrides/servers/Liberator/etc/rttpd.conf`, override the value of https-cipher-list to include ciphers from the TLS 1.0 cipher suite and higher. See the OWASP Cipher String Cheat Sheet and the Mozilla Security/Server Side TLS wiki page for guidance.

Syntax: `https-ssl-options <options>`

Type: string

Default value (Liberator 6): `SSL_OP_NO_SSLv2`

Default value (Liberator 7): `SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1`

Values accepted:

VALUE MEANING

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

You can combine multiple values using the bitwise `|` operator. The example below disables support for protocols SSLv2, SSLv3, and TLSv1:

`https-ssl-options 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`