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

Liberator’s key, key passphrase, and certificate are stored in the Deployment Framework directory <Framework-root>/global_config/ssl/

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

In versions of the Deployment Framework prior to 7.0.2, the Deployment Framework automatically copies demonstration SSL credentials on deployment of Liberator if no SSL credentials are found in the global_config/ssl directory. From version 7.0.2 of the Deployment Framework, to copy the demonstration SSL credentials, run the ./dfw copy-ssl-demo-files command.

The demonstration SSL credentials are suitable for use in development and testing. When you first connect to a Liberator that uses these sample credentials, your web browser will prompt you to trust the sample 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 your own certificate file, key file, and passphrase file:

  1. Optionally rename your production certificate, key, and passphrase files to Liberator’s default filenames: rttpd_https.pem, rttpd_https.key, and rttpd_https.pwd.

  2. Copy your production files to <Framework-root>/global_config/ssl/

If you have opted not to use the default names for Liberator’s HTTPS credentials files, you will need to declare your own filenames in Liberator’s configuration. Edit <Framework-root>/global_config/overrides/servers/Liberator/etc/rttpd.conf, and declare your file names using the configuration items below:

https-certificate   ${SSLCERT_PATH}/my-production-certificate-file
https-privatekey    ${SSLCERT_PATH}/my-production-key-file
https-passwordfile  ${SSLCERT_PATH}/my-production-passphrase-file

You can see from the example configuration above that a configuration macro SSLCERT_PATH is used to specify the directory path to the relevant files. For more information on configuration macros, see the Framework Configuration macros and items page.

While you are working in the <Framework-root>/global_config/ssl directory, you may want to take the opportunity to create 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 protocols

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: