Configure how Liberator handles HTTPS connections

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

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.

In production environments, always use HTTPS connections to Liberator, to ensure high security. Don’t use HTTP in production environments.
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’s 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. If you want to change the Liberator’s HTTP connection interface and/or HTTP port, set the following configuration items.

To change the Liberator’s HTTP port, add the macro definition LIBERATOR${THIS_LEG}_HTTPSPORT to the Deployment Framework file <Framework-root>/global_config/environment.conf

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

For example:

#
# Add updated configuration after this point
#
...
#
# Set Liberator's HTTPS port to the conventional default
#
define LIBERATOR${THIS_LEG}_HTTPSPORT 443
Don’t change value of the configuration item https-port directly. Always define the HTTP port using the macro LIBERATOR${THIS_LEG}_HTTPSPORT

If you want to restrict Liberator to listening 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 is used to define both the HTTP and HTTPS network interfaces – it’s assumed that HTTP and HTTPS will always use the same interface. So there’s no macro called LIBERATOR${THIS_LEG}_HTTPSINTERFACE)

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

For example:

#
# 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
Don’t change value of the configuration item https-interface directly. Always define the HTTP interface using the macro LIBERATOR${THIS_LEG}_HTTPINTERFACE

Applying the security policy

The Liberator install kit comes with a set of SSL files containing a certificate, private key and certificate passphrase that are suitable for development and testing purposes. The files were created using the OpenSSL toolkit and consist of:

  • An SSL certificate file in PEM format: rttpd_https.pem

  • An SSL private key file in PEM format rttpd_https.key

  • A file containing the SSL certificate passphrase: rttpd_https.pwd

When you deploy Liberator, these files are copied to the Deployment Framework directory <Framework-root>/global_config/ssl/, provided that there are no files already in this directory. (You may have production versions of the SSL files in the directory - see Setting certificates for production use, in which case, when you deploy a new version of Liberator, the production files aren’t replaced by the development versions.) When you enable Liberator’s built-in HTTPS Config blade, it uses the SSL files that it finds in <Framework-root>/global_config/ssl/

If you’re using the sample SSL files, you’ll need to tell your browser to accept the certificate even though it doesn’t recognise the authority and the certificate isn’t strictly for your installation of the Liberator server. The certificate and certificate authority use the passphrase: rttpdcert

For more about the OpenSSL toolkit, see www.openssl.org

Setting strong encryption (encryption key length)

To ensure adequate security In a production deployment, the encryption keys you use (as defined in the certificates -see Setting certificates for production use below ) must be at least 128 bits long.

Additionally, make sure that the list of SSL ciphers (cryptographic algorithms) available to Liberator includes ciphers that support keys of 128 bits or more. The ciphers are selected from the set available in the version of OpenSSL built into Liberator, and the list is specified by the Liberator configuration item https-cipher-list, which we recommend you define as follows:

https-cipher-list HIGH+TLSv1

This configuration setting ensures that HTTPS clients of Windows-based Liberators can use encryption keys of least 128 bits. Linux-based Liberators can use just the value HIGH, but HIGH+TLSV1 amounts to the same thing on LInux, so you can use the above configuration in both Windows and Linux environments.

In Liberators running under Windows, the configuration setting https-cipher-list HIGH won’t provide 128 bit encryption capability.

For more information about the OpenSSL 1.0.2 cipher list, see the OpenSSL ciphers(1) manual page, which includes a list of the available cipher suite names.

Setting certificates for production use

You must obtain your own certificate, private key and passphrase for production use. When you’ve done this:

  • Put the production files in <Framework-root>/global_config/ssl/

  • Configure the HTTPS blade to point at the new files.

    To do this, add the following entries to <Framework-root>/global_config/overrides/servers/Liberator/etc/rttpd.conf

https-certificate   ${SSLCERT_PATH}/.pem
https-privatekey    ${SSLCERT_PATH}/.key
https-passwordfile  ${SSLCERT_PATH}/.pwd

Where, of course, <my-production-certificate-file> and so on, are really the actual names of the files.

You can see from this example that in the Deployment Framework, a configuration macro SSLCERT_PATH is used to specify the directory path to the relevant files. See the Framework Configuration macros and items page.

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.

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: