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

Enabling HTTPS

Liberator is supplied with a built-in HTTPS Config blade (see Built-in blades), so to enable HTTPS you just activate the blade. To ensure maximum security, you should also disable HTTP connections by deactivating the built-in HTTP blade:

./dfw deactivate HTTP
./dfw activate HTTPS

Enabling the HTTPS blade makes the Deployment Framework use the blade configuration file <Framework-root>/kits/HTTPS/Liberator/etc/rttpd.conf. This file contains configuration items that

You can change the default settings of these configuration items as required - see the following sections.

If you’re enabling HTTPS for a production environment, you should disable Liberator’s built-in web pages too, by deactivating and activating the following built-in blades:

./dfw deactivate LiberatorWebsite
./dfw activate MinimalLiberatorWebsite

Configuring Liberator’s HTTPS port and interface

When you activate Liberator’s HTTPS Config blade, Liberator by default listens for HTTPS connections on all available interfaces, on port 18081.

Configuring the HTTPS port

To change the Liberator’s HTTPS port, add the macro definition LIBERATOR${THIS_LEG}_HTTPSPORT to the Deployment Framework file <Framework-root>/global_config/environment.conf. The macro sets the value of the configuration item https-port.

Do not set the value of https-port directly. Use the configuration macros provided by the Deployment Framework.

Insert the definition at the end of the section headed "Add updated configuration after this point".

#
# Add updated configuration after this point
#
...
#
# Set Liberator's HTTPS port to the conventional default
#
define LIBERATOR${THIS_LEG}_HTTPSPORT 443

Configuring the HTTPS interface

To restrict Liberator to listen for HTTPS connection requests on specific network interfaces, add the macro definition LIBERATOR${THIS_LEG}_HTTPINTERFACE to the Deployment Framework file <Framework-root>/global_config/environment.conf. This macro defines both the HTTP interfaces and the HTTPS interfaces; there’s no LIBERATOR${THIS_LEG}_HTTPSINTERFACE macro. The macro sets the value of the configuration item https-interface.

Do not set the value of https-interface directly. Use the configuration macros provided by the Deployment Framework.

The LIBERATOR${THIS_LEG}_HTTPINTERFACE macro supports IPv6 addresses from version 7 of Liberator. To listen for HTTPS connections on both IP addresses on a dual-stack network interface, assign the interface’s IPv4 address and IPv6 address to the macro.

Insert the definition at the end of the section headed "Add updated configuration after this point".

#
# Add updated configuration after this point
#
...
#
# Restrict Liberator's HTTPS interface to specific network interfaces
#
define LIBERATOR${THIS_LEG}_HTTPINTERFACE aaa.aaa.aaa.aaa bbb.bbb.bbb.bbb

Installing keys and certificates

When Liberator is deployed to the Deployment Framework, the default location for Liberator’s key, certificate, and passphrase files is the <Framework-root>/global_config/ssl/ directory.

Supported certificates

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

From versions 6.2.23, 7.0.5, and 7.1.1, Liberator ships with a new demonstration SSL certificate signed using the SHA-256 hashing algorithm. Prior to these versions, Liberator shipped with a demonstration certificate signed using the MD5 hashing algorithm. This change was made to maintain compatibility with StreamLink.NET 7.1 and other clients that drop support for MD5-signed certificates in the future.

To determine which hashing algorithm was used in the generation of your certificate’s digital signature, run the OpenSSL command below:

openssl x509 -in certfile -text -noout | grep 'Signature Algorithm'

where certfile is the file name of your certificate.

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

By default, Liberator is configured to use the following credential files for HTTPS connections:

File Description

<Framework-root>/global_config/ssl/rttpd_https.pem

Self-signed certificate in PEM format

<Framework-root>/global_config/ssl/rttpd_https.key

Encrypted private key in PEM format

<Framework-root>/global_config/ssl/rttpd_https.pwd

Passphrase for the private key

Prior to version 7.0.2, the Deployment Framework automatically copies Liberator’s demonstration SSL credentials on deployment of Liberator if no SSL credentials are found in the global_config/ssl directory.

From version 7.0.2, as a security precaution, the Deployment Framework does not automatically copy Liberator’s demonstration SSL credentials. To copy the demonstration SSL credentials manually, run the ./dfw copy-ssl-demo-files command.

Prior to version 7.1.1 of Liberator, the demonstration certificate is signed using an MD5 hash. From version 7.1.1 of Liberator, the demonstration certificate is signed using a SHA-256 hash. This change was made to maintain compatibility with StreamLink.NET 7.1 and other clients that drop support for MD5-signed certificates in the future.

The demonstration SSL credentials are suitable for use in development and testing only. The certificate is self-signed and not automatically trusted by web browsers. When you first connect to a Liberator that uses demonstration certificate, your web browser will prompt you to trust the certificate.

Do not use the demonstration SSL credentials in production.

To install keys and certificates for use in production, see Installing certificates for production use.

Installing certificates for production use

Follow the instructions below to install a production certificate:

  1. 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 Supported certificates above.

    The MD5 hashing algorithm, used to sign older certificates, is deprecated in the digital security industry and some platforms have dropped support for it. Caplin’s StreamLink.NET dropped support for MD5-signed certificates in version 7.1.

  2. 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, edit <Framework-root>/global_config/overrides/servers/Liberator/etc/rttpd.conf, and specify your own file names using the configuration items https-certificate, https-privatekey, and https-passwordfile.

    File: global_config/overrides/servers/Liberator/etc/rttpd.conf
    https-certificate   ${SSLCERT_PATH}/my-production-certificate-file
https-privatekey    ${SSLCERT_PATH}/my-production-key-file
https-passwordfile  ${SSLCERT_PATH}/my-production-passphrase-file

    The configuration macro {SSLCERT_PATH} is replaced with the path to the Deployment Framework’s SSL directory. See Configuration macros and items.

  3. Copy the key, certificate, and pass phrase file to the <Framework-root>/global_config/ssl/ directory.

  4. Generate a Diffie-Hellman parameters file, required by DHE and ECDHE ciphers. See Additional requirements for ephemeral Diffie-Hellman ciphers.

When you set up HTTPS connections to Liberator, you’ll probably want to set up secure direct connections at the same time (see How can I…​ Configure how Liberator handles direct client connections). In development and test environments, it’s convenient to share the same certificate, private key file and certificate pass phrase file between these two types of connection. But for added security in production environments, you can configure a different set of these files for each connection type.

Disabling older protocol versions

The following SSL and TLS protocol versions are enabled by default in Liberator.

Protocol versions permitted by default in Liberator
Liberator SSLv2 SSLv3 TLSv1 TLSv1.1 TLSv1.2

6.2.0–6.2.1

Not supported

Not supported

6.2.2+

7.0.1+

To disable older versions of the SSL/TLS protocol, use the https-ssl-options configuration item. As an example, the default value of https-ssl-options for Liberator 7 disables support for SSLv2, SSLv3, and TLSv1:

https-ssl-options SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1
In older versions of Internet Explorer (versions 8, 9, and 10), TLSv1.1 and TLSv1.2 are disabled by default. To connect an older version of Internet Explorer to Liberator 7, either enable TLSv1.1 and TLSv1.2 in Internet Explorer, or enable TLSv1 in Liberator 7.

Setting permitted ciphers

To specify the list of ciphers permitted in HTTPS communications, supply an OpenSSL cipher-list to the https-cipher-list configuration item.

Liberator’s default cipher list is not suitable for production use. Maintaining your own list of permitted ciphers should form part of your security policy. Industry best practices can change quickly, and you should regularly review the cipher list under the guidance of security professionals.

Example cipher list

The cipher lists in this section are provided for example purposes only. You should review the security of the lists before deploying either of them to production.

This example begins with ciphers of 128 bits or greater from the TLSv1.2 cipher suite, and then excludes all ciphers that are also in the RC4, DES, 3DES, MD5, and anonymous cipher suites.

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

For backwards compatibility with older clients that do not support TLSv1.2, the above example can be extended to include ciphers from the TLSv1 cipher suite.

https-cipher-list HIGH+TLSv1.2:HIGH+TLSv1:!RC4:!DES:!3DES:!MD5:!aNULL:!eNULL:!NULL
By default, Liberator 7 does not permit connections using TLSv1. To enable TLSv1 in Liberator 7, see https-ssl-options.

Additional requirements for ephemeral Diffie-Hellman ciphers

The ephemeral Diffie-Hellman cipher suites, DHE and ECDHE, are supported by Liberator from version 6.2.14 and 7.0.1. The DHE and ECDHE cipher suites provide forward secrecy (FS).

The DHE and ECDHE cipher suites require a Diffie-Hellman (DH) parameters file. If you include DHE and ECDHE ciphers in https-cipher-list but do not supply Liberator with the path to a DH parameters file, then Liberator will not include DHE and ECDHE ciphers in its list of supported ciphers during a SSL/TLS handshake.

To create a DH parameters file and supply Liberator with the path to it, follow the instructions below:

  1. Generate a DH parameters file from the command line using the OpenSSL dhparam command below. It will take several minutes to complete.

    openssl dhparam -out rttpd-dhparam-2048.pem 2048

  2. Move the generated rttpd-dhparam-2048.pem file to <Framework-root>/global_config/ssl/

  3. Add a https-dhparams configuration item to Liberator’s rttpd.conf and assign it the location of the DH parameters file.

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

  4. Restart Liberator

To test that the DH parameters file has been successfully installed, run the command below to test a connection using an ECDHE cipher. Replace host and port with the host and port of Liberator’s HTTPS interface respectively. The command requires OpenSSL 1.0.1 or higher.

openssl s_client -cipher ECDHE-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.

See also: