Configure how Liberator handles HTTPS connections

Here’s how to configure Liberator’s HTTPS connections.

In production environments, always use HTTPS connections to Liberator, to ensure high security. Don’t use HTTP in production environments.

HTTPS is the secure version of HTTP that uses the Secure Sockets Layer of TCP/IP (SSL) and offers a much greater level of protection than standard HTTP transmission. Liberator can run as an HTTPS web server like most common web servers. Web pages and other standard HTTP traffic can be sent over HTTPS, and if HTTPS is enabled all RTTP data is sent over an HTTPS connection too.

Liberator supports standard TLS server-side certificates to authenticate the server to the client. They must be generated and signed by a certificate authority.

Some of the instructions on this page require you to use the dfw command of the Deployment Framework. Before entering any dfw command as ./dfw <command-name>, make sure your current (working) directory is set to the Deployment Framework’s topmost directory. For a list of dfw commands, click here.

Contents:

Liberator’s TLS implementation
Enabling Liberator’s HTTPS interface
Configuring the HTTPS port number
Configuring the HTTPS network interface
Installing a TLS key and certificate
Configuring supported TLS protocol versions
Configuring supported TLS ciphers
Example HTTPS configuration
Generating a Diffie-Hellman parameters file for DHE ciphers
Seeding the OpenSSL random number generator
Configuring OpenSSL
Further reading on TLS

Liberator’s TLS implementation

Liberator uses OpenSSL to provide its implementation of TLS. The OpenSSL library is built-in to Liberator and is independent of the host system’s installation of OpenSSL.

To determine the version of OpenSSL bundled with a specific release of Liberator, see Liberator’s release notes or run the strings command on the Liberator binary and grep the output:

$ strings rttpd | grep -i '^openssl [0-9]'

Enabling Liberator’s HTTPS interface

Liberator’s default HTTP and HTTPS configuration is provided in two feature blades ( config blades): HTTP and HTTPS.

The HTTP feature blade is activated by default.

To deactivate HTTP and activate HTTPS, follow the steps below:

Run the commands below to deactivate the HTTP blade and activate the HTTPS blade:
```
./dfw deactivate HTTP
./dfw activate HTTPS
```
Configure the HTTPS port number (default 18081). See Configuring the HTTPS port number.
Configure the HTTPS network interface (default all interfaces). See Configuring the HTTPS network interface.
Install a TLS key, password file, and certificate. See Installing a TLS key and certificate.
Configure TLS protocol support (you should also repeat this task periodically as part of a regular security review). See Configuring supported TLS protocol versions.
Configure TLS cipher support (you should also repeat this task periodically as part of a regular security review). See Configuring supported TLS ciphers.
Generate a Diffie-Hellman (DH) parameters file to allow Liberator to use ephemeral Diffie-Hellman (DHE) ciphers. See Generating a Diffie-Hellman parameters file for DHE ciphers.
If this is a production server, disable Liberator’s built-in administrator website:
```
./dfw deactivate LiberatorWebsite
./dfw activate MinimalLiberatorWebsite
```
If this is a production server, enable TLS for Liberator’s direct RTTP interface too, or disable the direct RTTP interface entirely. See Configure how Liberator handles direct client connections for more information.

Configuring the HTTPS port number

By default, Liberator’s HTTPS port is 18081. If you plan to route Internet traffic to Liberator’s HTTPS interface, then for the broadest compatibility with your customers' firewall policies, we recommend that you expose Liberator’s HTTPS interface on port 443.

The easiest way to expose Liberator’s HTTPS interface on port 443 is to use port-forwarding on your gateway firewall to route incoming traffic on 443 to port 18081 on your Liberator server.

Alternatively, follow the instructions below to bind Liberator’s HTTPS interface to port 443 on the Liberator host:

In the Deployment Framework’s global_config/environment.conf file, set the LIBERATOR${THIS_LEG}_HTTPSPORT configuration variable to 443:
```
define LIBERATOR${THIS_LEG}_HTTPSPORT 443
```
Do not set the value of the https-port configuration item directly. Redefine the LIBERATOR${THIS_LEG}_HTTPSPORT configuration variable instead.
Run the system command below to permit the Liberator binary to bind to port 443:
```
$ sudo setcap 'cap_net_bind_service=+ep' dfw_root/kits/Liberator/Latest/bin/rttpd
```
where dfw_root is the path to your Deployment Framework.

Configuring the HTTPS network interface

By default, Liberator’s HTTP and HTTPS server sockets are bound to all network interfaces on Liberator’s host.

To bind Liberator’s HTTP and HTTPS server sockets to specific network interfaces, redefine the LIBERATOR${THIS_LEG}_HTTPINTERFACE configuration variable in the <Framework-root>/global_config/environment.conf file:

Binding Liberator’s HTTP and HTTPS sockets to two network addresses

define LIBERATOR${THIS_LEG}_HTTPINTERFACE 203.0.113.1 198.51.100.11

The configuration variable supports IPv6 addresses from version 7 of Liberator. To listen for connections on both the IPv4 and IPv6 address of a dual-stack network interface, assign both the IPv4 and IPv6 addresses to the configuration variable.

Despite the name of the LIBERATOR${THIS_LEG}_HTTPINTERFACE variable implying that it applies only to HTTP server sockets, the variable applies to both HTTP and HTTPS server sockets.

Do not set the value of the https-interface configuration item directly. Redefine the LIBERATOR${THIS_LEG}_HTTPINTERFACE configuration variable instead.

Installing a TLS key and certificate

This section describes how to install a key, key password file, and certificate.

Default key and certificate paths

By default, the Deployment Framework (DFW) expects keys and certificates to be stored in the global_config/ssl directory. For convenience in writing configuration, the Deployment Framework sets a configuration variable SSLCERT_PATH to this directory.

For a full list of Deployment Framework configuration variables, see Configuration macros and items.

Liberator’s HTTPS feature blade configures default key and certificate locations as follows:

Default key, passphrase, and certificate paths
File	Configuration item	Default value
Certificate	`https-certificate`	`global_config/ssl/rttpd_https.pem`
Private key	`https-privatekey`	`global_config/ssl/rttpd_https.key`
Private-key passphrase	`https-passwordfile`	`global_config/ssl/rttpd_https.pwd`

To override the default paths, assign new values to the https-certificate, https-privatekey, and https-passwordfile configuration items in the Deployment Framework file global_config/overrides/servers/Liberator/etc/rttpd.conf.

Deprecation of certificates with MD5- and SHA1-based digital signatures

Certificates signed with an MD5 hash with RSA encryption have long been deprecated and some platforms and libraries no longer support them. The digital security industry now recommends using the SHA-2 family of hashing algorithms in digital signatures.

Liberator’s demonstration self-signed SSL certificate was re-issued with a SHA256-based digital signature in versions 6.2.23, 7.0.5, and 7.1.1 of Liberator. Liberator 7.1 continues to support certificates signed with an MD5 hashing algorithm, but support may be dropped in future.

StreamLink.NET 7.1 is compiled with .NET 4.6, which does not support certificates signed with the MD5 hashing algorithm.

To determine the digital signature algorithm used in a certificate, use OpenSSL’s x509 command to read the certificate and then grep the output:

Determining the digital signature algorithm in certificate 'rttpd_https.pem'

$ openssl x509 -in rttpd_https.pem -text -noout | grep -m1 'Signature Algorithm'
    Signature Algorithm: sha256WithRSAEncryption

Digital signature algorithms used in certificates
Algorithm	Status	Notes
md5WithRSAEncryption	Deprecated	Not supported by Caplin’s StreamLink.NET 7.1.
sha1WithRSAEncryption	Deprecated	See SHA1 Deprecation: What you need to know on the Qualys blog.
sha256WithRSAEncryption	Recommended

Installing certificates for development and testing

For the convenience of developers and software testers, Caplin ships a self-signed demonstration certificate with Liberator.

Do not use Caplin’s self-signed certificate in production.

In versions of the Deployment Framework prior to 7.0.2, the Deployment Framework automatically deploys Caplin’s self-signed certificate with Liberator if no keys and certificate exist for Liberator in the global_config/ssl directory.

From version 7.0.2 of the Deployment Framework, the Deployment Framework does not automatically deploy Caplin’s self-signed certificate with Liberator. To manually deploy the self-signed certificate, run the copy-ssl-demo-files Deployment Framework command:

./dfw copy-ssl-demo-files

When you first connect a web browser to a Liberator that presents Caplin’s self-signed certificate, your web browser will prompt you to trust the certificate.

Installing certificates for production use

Follow the instructions below to install a production certificate:

Follow the instructions provided by your chosen certificate authority (CA) to generate a certificate signing request (CSR) for your Liberator host. When generating the CSR, we recommend that you specify a SHA-2 hashing algorithm or stronger. See Deprecation of certificates with MD5- and SHA1-based digital signatures above.
When your CA delivers a signed certificate, rename the certificate, key, and passphrase files to Liberator’s default file names: rttpd_https.pem, rttpd_https.key, and rttpd_https.pwd.

If you don’t want to use Liberator’s default file names, assign your own file names to the configuration items https-certificate, https-privatekey, and https-passwordfile in the file global_config/overrides/servers/Liberator/etc/rttpd.conf.
Copy the private key, certificate, and password files to the <Framework-root>/global_config/ssl/ directory.

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

From Liberator 7.1.9: If the private 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.

Configuring supported TLS protocol versions

To specify which TLS protocol versions are supported by Liberator, use the https-ssl-options configuration item to disable protocol versions.

For guidance on choosing which TLS protocol versions to support, see Further reading on TLS below.

Default TLS protocol versions

The default TLS configuration is not updated regularly and is for your initial convenience only; it is not a security recommendation.

All protocols supported by the version of OpenSSL included with Liberator are enabled unless explicitly disabled by https-ssl-options.

Default TLS protocols
Liberator	SSL 2 ^*	TLS 1.1 ^‡	TLS 1.2	TLS 1.3
7.1.25	-
7.1.5	-
7.1.2	-			-
7.0.1				-
6.2.2				-
6.2.0		-	-	-

- Protocol not available
Protocol disabled (see https-ssl-options)
Protocol enabled
* The IETF prohibited SSL 2 in March 2011: RFC 6176
† The IETF deprecated SSL 3 in June 2015: RFC 7568
‡ The IETF deprecated TLS 1.0 and TLS 1.1 in March 2021: RFC 8996

Worked example

The configuration in this example is provided for illustrative purposes only, is not updated regularly, and does not constitute security advice. Review all TLS configuration before deploying to production, and schedule regular reviews thereafter.

Liberator 7.1.24’s TLS implementation supports SSL 3, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3. By default, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3 are enabled on the HTTPS interface (see Default TLS protocol versions, below).

To configure Liberator 7.1.24 so that only TLS 1.2 and TLS 1.3 are enabled on the HTTPS interface, set https-ssl-options to disable SSL 3, TLS 1.0, and TLS 1.1:

https-ssl-options SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1|SSL_OP_NO_TLSv1_1

For a complete HTTPS configuration example, see Example HTTPS configuration below.

Configuring supported TLS ciphers

To specify which TLS 1.0, 1.1 and 1.2 ciphers are supported by Liberator, set https-cipher-list to an OpenSSL cipher list.

To specify which TLS 1.3 ciphers are supported by Liberator, set https-ciphersuites to an OpenSSL cipher list. This is an advanced configuration option and is not required to enable support for TLS 1.3.

For guidance on deciding which TLS ciphers to support, see Further reading on TLS below.

In accordance with the TLS specification, when choosing a cipher for a TLS 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.

If your cipher list includes ephemeral Diffie-Hellman (DHE) ciphers, then configure the https-dhparams configuration item with the location of a valid Diffie-Hellman (DH) parameters file. If you fail to do so, Liberator silently drops DHE ciphers from its list of supported ciphers. See Generating a Diffie-Hellman parameters file for DHE ciphers.

Default cipher list

The default TLS configuration is not updated regularly and is for your initial convenience only; it is not a security recommendation.

Default cipher string
Liberator	Cipher string
7.1.25	`TLSv1.2+ECDHE+AESGCM:TLSv1.2+ECDHE+AESCCM:TLSv1.2+ECDHE+CHACHA20:TLSv1.2+DHE+AESGCM:TLSv1.2+DHE+AESCCM:TLSv1.2+DHE+CHACHA20`
7.1.5	`ECDHE:DHE:!SSLv3:!SSLv2:@STRENGTH`
7.0.1	`DEFAULT:!RC4-SHA:!RC4-MD5:!DES-CBC3-SHA`
6.0.0	`DEFAULT`

From Liberator 7.1.5, only cipher suites that support forward secrecy (ECDHE and DHE) are enabled by default. DHE ciphers require a Diffie-Hellman parameters file, which is not distributed with Liberator (see Generating a Diffie-Hellman parameters file for DHE ciphers).

Preparing a cipher list

You can preview how Liberator’s OpenSSL will interpret a cipher list by using the openssl ciphers command. For accuracy, use a version of OpenSSL that matches the version of OpenSSL used by your version of Liberator (see Liberator’s TLS implementation).

For example, to expand the cipher list ECDHE+TLSv1.2 DHE+TLSv1.2 to individual cipher names, use the command below:

$ openssl ciphers -v 'ECDHE+TLSv1.2 DHE+TLSv1.2' | column -t

The openssl cipher command’s output uses OpenSSL cipher names, but security literature and vulnerability scanners often use IANA cipher names. To translate between the two naming schemes, refer to the table on Security: Cipher Suites on the Mozilla wiki.

Worked example

A Liberator has been configured to support only TLS versions 1.2 and 1.3:

https-ssl-options SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1|SSL_OP_NO_TLSv1_1

In this example, we’ll construct an OpenSSL cipher list of TLS 1.2 ciphers. TLS 1.3 ciphers are automatically included by OpenSSL and do not need to be configured.

The Qualys SSL Labs recommendations at the time of writing (June 2022) state that the following cipher suites must be preferred:

AEAD (Authenticated Encryption with Associated Data) cipher suites: CHACHA20_POLY1305, AES with GCM, and AES with CCM
PFS (Perfect Forward Secrecy) ciphers: ECDHE_RSA, ECDHE_ECDSA, DHE_RSA, DHE_DSS, CECPQ1 and all TLS 1.3 ciphers

We’ll use the following OpenSSL cipher strings to construct our cipher list:

Cipher string Description

Cipher string	Description
`TLSv1.2`	All TLS 1.2 ciphers
`ECHDE`	All ciphers using authenticated ephemeral ECDH key agreement.
`DHE`	All ciphers using authenticated ephemeral DH key agreement.
`AESGCM`	All ciphers that use AES-GCM encryption
`AESCCM`	All ciphers that use AES-CCM encryption
`CHACHA20`	All ciphers that use ChaCha20 encryption

TLSv1.2

All TLS 1.2 ciphers

ECHDE

All ciphers using authenticated ephemeral ECDH key agreement.

DHE

All ciphers using authenticated ephemeral DH key agreement.

AESGCM

All ciphers that use AES-GCM encryption

AESCCM

All ciphers that use AES-CCM encryption

CHACHA20

All ciphers that use ChaCha20 encryption

We use the OpenSSL cipher-string logical AND (+) operator to combine the cipher strings into six subsets:

TLSv1.2+ECDHE+AESGCM
TLSv1.2+ECDHE+AESCCM
TLSv1.2+ECDHE+CHACHA20
TLSv1.2+DHE+AESGCM
TSLv1.2+DHE+AESCCM
TSLv1.2+DHE+CHACHA20

We then assign this list to https-ssl-ciphers:

https-ssl-ciphers "TLSv1.2+ECDHE+AESGCM TLSv1.2+ECDHE+AESCCM TLSv1.2+ECDHE+CHACHA20 TLSv1.2+DHE+AESGCM TLSv1.2+DHE+AESCCM TLSv1.2+DHE+CHACHA20"

In an OpenSSL cipher list, cipher strings can be separated by spaces or colons (:). We have used spaces for clarity. When separated by spaces, the cipher list must be enclosed in quotes.

For a complete HTTPS configuration example, see Example HTTPS configuration below.

Example HTTPS configuration

The configuration in this section is provided for illustrative purposes only, is not updated regularly, and does not constitute security advice. Review all TLS configuration before deploying to production, and schedule regular reviews thereafter.

This example supports modern web clients (defined as all clients that support TLS 1.2 and above).

Features:

TLS protocols: TLS 1.2, TLS 1.3 (Liberator supports TLS 1.3 from Liberator 7.1.5)
TLS 1.3 ciphers: All mandatory ciphers
TLS 1.2 ciphers: Forward-secrecy ciphers (ECDHE, DHE) that implement AES-GCM, AES-CCM, or CHACHA20 encryption.
Diffie-Hellman parameters: 2048-bit

When tested with Liberator 7.1.24 using the SSL Labs Server Test on 5 June 2022, the configuration below scored A+. View the SSL Labs report.

While the configuration below achieved an SSL Labs score of A+ on 5 June 2022, ciphers may weaken over time and the configuration may not achieve that score today. Retest and review this configuration before considering deploying it to production.

# OpenSSL options
define SSL_OPTIONS "SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1|SSL_OP_NO_TLSv1_1"

# OpenSSL ciphers to include
define CIPHER_INCLUDES "ECDHE+TLSv1.2+AESGCM ECDHE+TLSv1.2+AESCCM ECDHE+TLSv1.2+CHACHA20 DHE+TLSv1.2+AESGCM DHE+TLSv1.2+AESCCM DHE+TLSv1.2+CHACHA20"

# OpenSSL ciphers to exclude
define CIPHER_EXCLUDES ""

https-ssl-options  "${SSL_OPTIONS}"
https-cipher-list  "${CIPHER_INCLUDES} ${CIPHER_EXCLUDES}"
https-dhparams     "${SSLCERT_PATH}/rttpd-dhparam-2048.pem"

Generating a Diffie-Hellman parameters file for DHE ciphers

Ephemeral Diffie-Hellman ciphers (DHE) ciphers are supported by Liberator from version 6.2.14 and 7.0.1.

DHE ciphers require a Diffie-Hellman (DH) parameter file. If you do not configure the https-dhparams configuration item with the location of a valid DH parameters file, Liberator silently removes DHE ciphers from its list of supported ciphers.

No DH parameters file is provided with Liberator; you must generate your own.

To generate a Diffie-Hellman (DH) parameters file, follow the steps below:

In the Deployment Framework’s global_config/ssl/ directory, run the command below:
```
$ openssl dhparam -out rttpd-dhparam-2048.pem 2048
```
This command can take a long time to complete.
Assign the location of the DH parameters file to the https-dhparams configuration item in the Deployment Framework’s global_config/overrides/servers/Liberator/etc/rttpd.conf file:
```
https-dhparams ${SSLCERT_PATH}/rttpd-dhparam-2048.pem
```

To test that a Liberator supports DHE ciphers, follow the steps below:

In the file global_config/overrides/servers/Liberator/rttpd.conf, assign a cipher string containing DHE ciphers to the https-cipher-list configuration item. For example:
```
https-cipher-list "ECDHE+TLSv1.2:DHE+TLSv1.2"
```
Restart Liberator
Run the command below to test connecting to Liberator using a DHE cipher. The example below tests connecting with the DHE-RSA-AES256-GCM-SHA384 cipher, one of the DHE ciphers included in OpenSSL’s TLS 1.2 cipher suite:
```
$ openssl s_client -cipher DHE-RSA-AES256-GCM-SHA384 -connect host:port
```

Seeding the OpenSSL random number generator

See How can I… Seed the OpenSSL random number generator.

Configuring OpenSSL

Liberator uses the OpenSSL software to implement the security policies for secure (HTTPS) connections with clients. You can configure OpenSSL using the following DataSource configuration items, which are defined on the page DataSource Secure Sockets Layer (SSL) configuration:

When you change the configuration of OpenSSL, the new settings apply to all of Liberator’s secure (SSL) connections: HTTPS connections, Direct secure connections to clients, and secure connections between Liberator and other DataSource applications.