Configure how Liberator handles direct client connections

Here's how to configure direct RTTP connections between clients and Liberator, including secure connections via SSL.

Liberator can accept direct persistent RTTP connections from StreamLink clients via TCP/IP, rather than via HTTP or HTTPS.  The client connects to Liberator via a TCP/IP socket, and the Liberator streams data directly to the client across this connection. Direct connections can also use the Secure Sockets Layer (SSL) to provide greater security.

The instructions below on setting up secure (SSL) direct conections apply to Liberator 6.2 release and later, deployed using the Caplin Platform Deployment Framework release 6.2 and later.
Tip: 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:

Configuring Liberator’s direct port and interface

When you install Liberator to run under the Caplin Platform Deployment Framework, it’s automatically configured to use direct connections through a built-in Config blade called DirectConnection. The Liberator listens for direct connections on all available interfaces, on port 14001.

Warning! This type of connection isn't secure. In a production installation, clients shouldn't be allowed to connect to Liberator through such connections, for security reasons. Use secure direct (SSL) connections instead - see Enabling secure connections (SSL) below. 

Configuring the direct port

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

Important: Do not set the value of direct-port directly. Use the configuration macro 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 Direct port
#
define LIBERATOR${THIS_LEG}_DIRECTPORT 14051

Configuring the direct interface

To restrict Liberator to to listen for direct connection requests on specific network interfaces, add the macro definition LIBERATOR${THIS_LEG}_DIRECTINTERFACE to the Deployment Framework file <Framework-root>/global_config/environment.conf. The macro sets the value of the direct-interface configuration item.

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

This configuration macro supports IPv6 addresses from version 7 of Liberator. To listen for 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 direct interface to specific network interfaces
#
define LIBERATOR${THIS_LEG}_DIRECTINTERFACE aaa.aaa.aaa.aaa bbb.bbb.bbb.bbb

Enabling secure direct connections (SSL)

In the Caplin Deployment Framework release 6.2 and later, Liberator’s supplied with a built-in Config blade called DirectSSLConnection that implements secure direct connections using the OpenSSL implementation of SSL (see Built-in blades). To enable secure direct connections, just activate this blade. To ensure maximum security, you should also disable non-secure direct connections by deactivating the built-in DirectConnection blade:

./dfw deactivate DirectConnection
./dfw activate DirectSSLConnection

Enabling the DirectConnection blade makes the Deployment Framework use the blade configuration file <Framework-root>/kits/DirectSSLConnection/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.

Configuring the direct SSL port and interface

When you activate Liberator’s DirectSSLConnection Config blade, Liberator by default listens for direct connections on all available interfaces, on port 14002. If you want to change the Liberator's direct SSL connection interface and/or port, set the following configuration items.

Configuring the direct SSL port

To change the Liberator’s Direct SSL port, add the macro definition LIBERATOR${THIS_LEG}_DIRECTSSLPORT 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"

#
# Add updated configuration after this point
#
...
#
# Set Liberator's Direct SSL port
#
define LIBERATOR${THIS_LEG}_DIRECTSSLPORT 14052
Don’t change the value of the configuration item directssl-port directly. Always define the HTTP port using the macro LIBERATOR${THIS_LEG}_DIRECTSSLPORT

Configuring the direct SSL interface

To restrict Liberator to listen for direct SSL connection requests on specific network interfaces, add the macro definition LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE to the Deployment Framework file <Framework-root>/global_config/environment.conf

This configuration macro supports IPv6 addresses from version 7 of Liberator.

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 Direct SSL interface to specific network interfaces
#
define LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE aaa.aaa.aaa.aaa bbb.bbb.bbb.bbb
Don’t change the value of the configuration item directssl-interface directly. Always define the HTTP interface using the macro LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE

Installing keys and certificates

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

Setting certificates for development and testing

When you deploy Liberator, if no files are found in <Framework-root>/global_config/ssl/, a set of sample SSL credential files are copied to the directory.

File Description
rttpd_https.pem A self-signed certificate in PEM format
rttpd_https.key Private key in PEM format
rttpd_https.pwd Passphrase for the private key

These sample files 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.

To install your own SSL credential files, see Setting certificates for production use.

Setting certificates for production use

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

  1. Put the production files in <Framework-root>/global_config/ssl/
  2. Edit <Framework-root>/global_config/overrides/servers/Liberator/etc/rttpd.conf, and supply the correct file names to the configuration items below:
directssl-certificate   ${SSLCERT_PATH}/<my-production-certificate-file>.pem
directssl-privatekey    ${SSLCERT_PATH}/<my-production-key-file>.key
directssl-passwordfile  ${SSLCERT_PATH}/<my-production-passphrase-file>.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.

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.

Tip: When you set up direct connections to Liberator, you'll probably want to set up HTTPS connections at the same time (see How can I... Configure how Liberator handles HTTPS 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.

Protocols 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 direct-ssl-options configuration item. As an example, the default value of directssl-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

Note: In older clients, TLSv1.1 and TLSv1.2 may not be supported or may be disabled by default. To connect an older client to Liberator 7, either enable TLSv1.1 and TLSv1.2 in the client, 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 directssl-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

Note: By default, Liberator 7 does not permit connections using TLSv1. To enable TLSv1 in Liberator 7, see directssl-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 directssl-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.
    1. 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 directssl-dhparams configuration item to Liberator's rttpd.conf and assign it the location of the DH parameters file.
    1. 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 direct 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: Direct secure connections to clients, HTTPS connections and secure connections between Liberator and other DataSource applications.

Improving the security of direct connections

To resist attacks on your system, Liberator includes a configuration option called direct-max-line-length that limits the length of an RTTP message sent across a direct connection. If Liberator receives a message longer than that configured, it'll reject it rather than reading it continuously until memory runs out.

The default setting for this item should be sufficient, but if you experience security problems, set it to a lower value. Add the new setting to the Deployment Framework file <Framework-root>/global_config/overrides/servers/Liberator/etc/rttpd.conf


See also: