Configure how Liberator handles direct client connections

Here’s how to configure direct real-time text protocol (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 connections apply to Liberator 6.2 release and later, deployed using the Caplin Platform Deployment Framework release 6.2 and later.

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.

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.

This type of connection isn’t secure. In a production installation, use direct connections over SSL 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.

Do not set the value of the configuration item 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 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.

Do not set the value of the configuration item 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 is 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, run the commands below from the root directory of your Deployment Framework:

./dfw deactivate DirectConnection
./dfw activate DirectSSLConnection

Enabling the DirectSSLConnection blade makes the Deployment Framework use the blade configuration file <Framework-root>/kits/DirectSSLConnection/Liberator/etc/rttpd.conf. This file contains configuration items to the following specification:

Configuring the direct SSL port and interface

When you activate Liberator’s DirectSSLConnection config blade, Liberator by default listens for direct connections on port 14002 on all available interfaces. 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

The value of the LIBERATOR${THIS_LEG}_DIRECTSSLPORT macro is assigned to the directssl-port configuration item.

Don’t change the value of the configuration item directssl-port directly. Always define the port using the macro LIBERATOR${THIS_LEG}_DIRECTSSLPORT.

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

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

The value of the LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE macro is assigned to the directssl-interface configuration item.

Don’t change the value of the configuration item directssl-interface directly. Always define the interface using the macro LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE

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

Installing keys and certificates

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

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

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.

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 your own SSL credential files, 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 directssl-certificate, directssl-privatekey, and directssl-passwordfile.

    File: global_config/overrides/servers/Liberator/etc/rttpd.conf
    directssl-certificate   ${SSLCERT_PATH}/my-production-certificate-file
    directssl-privatekey    ${SSLCERT_PATH}/my-production-key-file
    directssl-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 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
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
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.

    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.

    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

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: