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.

Tip: Liberator is supplied with a built-in HTTPS Config blade (see Built-in blades) that you activate to enable HTTPS connections. For details on how to do this and how to change the blade's configuration, see How can I...  Configure how Liberator handles HTTPS connections.
Tip: You may also need to set ssl-random-seed, which configures the seeding of the OpenSSL random number generator that the Liberator uses for HTTPS and direct secure connections.

Contents:

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 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 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 hostnames 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 overidden for specific virtual host connections by the https-certificate option of the add-virtual-host that defines the virtual host.

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 certificate filename and path set up by default in the Liberator supplied with the Framework is
<Framework-root>/global_config/ssl/rttpd_https.pem This certificate file is shared between HTTPS and Direct SSL connections.
Liberator is supplied with an rttpd_https.pem file that's automatically copied to <Framework-root>/global_config/ssl/ when you deploy the Liberator to the Framework, unless you've previously put your own version of this file in the directory.

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

Type: string

Default value: cert.pem

The default filename for the certificate is the same as the private key's default filename (default for https-privatekey) because both the certificate and the private key can be contained in the same file.

https-cipher-list

https-cipher-list specifes 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.

Note: In Liberator 7, the protocols SSLv2, SSLv3, and TLSv1 are disabled by default. This configuration is not compatible with older versions of Internet Explorer (8, 9, and 10), in which the later versions of TLS (v1.1 and v1.2) are disabled by default. To re-enable TLSv1 in Liberator 7, set the value for https_ssl_options to SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3, and check that the value of https-cipher-list contains ciphers from the TLSv1 cipher suite.

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

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.

Note: supported from Liberator 7.0.2

Tip: 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

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 overidden for specific virtual host connections by the https-passwordfile option of the add-virtual-host that defines the virtual host.

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.
The password filename and path set up by default in the Liberator supplied with the Framework is
<Framework-root>/global_config/ssl/rttpd_https.pwd This password file is shared between HTTPS and Direct SSL connections.
Liberator is supplied with an rttpd_https.pwd file that's automatically copied to <Framework-root>/global_config/ssl/ when you deploy the Liberator to the Framework, unless you've previously put your own version of this file in the directory.

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

Type: string

Default value: rttpd.https.pass

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.  This file must be in PEM format. The directory path is optional and can be in relative or absolute format.

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

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 key filename and path set up by default in the Liberator supplied with the Framework is <Framework-root>/global_config/ssl/rttpd_https.key This private key file is shared between HTTPS and Direct SSL connections. Liberator is supplied with an rttpd_https.key file that's automatically copied to <Framework-root>/global_config/ssl/ when you deploy the Liberator to the Framework, unless you've previously put your own version of this file in the directory.

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

Type: string

Default value: cert.pem

The default filename for the private key is the same as the certificate's default filename (default for https-certificate) because both the certificate and the private key can be contained in the same file.

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.

Note: In Liberator 7, the protocols SSLv2, SSLv3, and TLSv1 are disabled by default. This configuration is not compatible with older versions of Internet Explorer (8, 9, and 10), in which the later versions of TLS (v1.1 and v1.2) are disabled by default. To re-enable TLSv1 in Liberator 7, set the value for https_ssl_options to SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3, and check that the value of https-cipher-list contains ciphers from the TLSv1 cipher suite.

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

See ssl-random-seed in DataSource Secure Sockets Layer (SSL) configuration.


See also: