Configure how Liberator handles direct client connections

This page describes how to configure Liberator’s interface for direct (RTTP over TCP/IP) connections from StreamLink clients.

To configure Liberator’s interface for StreamLink connections that are encapsulated in HTTP, HTTPS, and WebSocket protocols, see Configure how Liberator handles HTTP connections and Configure how Liberator handles HTTPS connections.

Direct connections are supported by all StreamLink libraries except for StreamLink JS. For more information on connection types, see StreamLink connection types.

Direct connections can also use SSL/TLS to provide greater security. The instructions below on setting up secure direct connections apply to Liberator 6.2 release and later, deployed using the Caplin Platform Deployment Framework release 6.2 and later.

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

By default, Liberator’s direct RTTP port is 14001. To change the direct port, redefine the LIBERATOR${THIS_LEG}_DIRECTPORT configuration variable in the Deployment Framework’s global_config/environment.conf file:

Setting Liberator’s direct RTTP port to 14051
define LIBERATOR${THIS_LEG}_DIRECTPORT 14051
Do not set the value of the configuration item direct-port directly. Redefine the LIBERATOR${THIS_LEG}_DIRECTPORT configuration variable instead.

Configuring the direct interface

By default, Liberator’s direct and direct SSL server sockets are bound to all network interfaces on Liberator’s host. To bind Liberator’s direct server sockets to one or more network interfaces, redefine the LIBERATOR${THIS_LEG}_DIRECTINTERFACE configuration variable in the Deployment Framework’s global_config/environment.conf file:

Binding Liberator’s direct sockets to two network addresses
define LIBERATOR${THIS_LEG}_DIRECTINTERFACE 203.0.113.1 198.51.100.11

The configuration variable supports IPv6 addresses from version 7 of Liberator. To listen for connections on both the IPv4 and IPv6 address of a dual-stack network interface, assign both IP addresses to the macro.

Despite the name of the LIBERATOR${THIS_LEG}_DIRECTINTERFACE variable implying that it applies only to the non-SSL direct server socket, the variable applies to both the direct and direct SSL server sockets.

Do not set the value of the configuration item direct-interface directly. Redefine the LIBERATOR${THIS_LEG}_DIRECTINTERFACE configuration variable instead.

Enabling secure (SSL) direct connections

Liberator’s direct RTTP configuration is provided in two feature blades (config blades): DirectConnection and DirectSSLConnection.

The DirectConnection feature blade is activated by default.

To enable secure direct connections, follow the steps below:

  1. Run the commands below to deactivate the DirectConnection blade and activate the DirectSSLConnection blade:

    ./dfw deactivate DirectConnection
    ./dfw activate DirectSSLConnection
  2. Review the default direct SSL port and interface. See Configuring the direct SSL port and Configuring the direct SSL interface.

  3. Install an SSL/TLS key, password file, and certificate. See Installing keys and certificates.

  4. Review the SSL/TLS protocols and ciphers supported by Liberator’s HTTPS interface (you should also repeat this task periodically as part of a regular security review). See Configuring support for SSL/TLS protocols and ciphers.

  5. Generate a Diffie-Hellman (DH) parameters file to allow Liberator to use ephemeral Diffie-Hellman (DHE) ciphers. See Enabling support for ephemeral Diffie-Hellman (DHE) ciphers.

  6. If this is a production server, disable Liberator’s built-in administrator website:

    ./dfw deactivate LiberatorWebsite
    ./dfw activate MinimalLiberatorWebsite
  7. If this is a production server, enable SSL/TLS for Liberator’s HTTP interface. See Configure how Liberator handles HTTPS connections for more information.

OpenSSL

Liberator uses its own copy of OpenSSL, compiled into Liberator at build time.

To determine the version of OpenSSL bundled with a specific release of Liberator, see Liberator’s release notes or run the strings command on the Liberator binary and grep the output:

strings rttpd | grep -i -m1 'openssl [0-9]'

Configuring the direct SSL port

By default, Liberator’s direct SSL port is 14002.To change the HTTPS port, redefine the LIBERATOR${THIS_LEG}_DIRECTSSLPORT configuration variable in the <Framework-root>/global_config/environment.conf file:

Setting Liberator’s direct SSL port to 14052
define LIBERATOR${THIS_LEG}_DIRECTSSLPORT 14052
Do not set the value of the directssl-port configuration item directly. Redefine the LIBERATOR${THIS_LEG}_DIRECTSSLPORT configuration variable instead.

Configuring the direct SSL interface

By default, Liberator’s direct SSL server socket is bound to all network interfaces on Liberator’s host. To bind Liberator’s direct SSL server socket to specific network interfaces, redefine the LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE configuration variable in the <Framework-root>/global_config/environment.conf file:

Binding Liberator’s direct SSL socket to two network interfaces
define LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE 203.0.113.1 198.51.100.11
Do not set the value of the directssl-interface configuration item directly. Redefine the LIBERATOR${THIS_LEG}_DIRECTSSLINTERFACE configuration variable instead.

Installing keys and certificates

This section describes how to install a key, key password file, and certificate.

Default key and certificate paths

By default, the Deployment Framework (DFW) expects keys and certificates to be stored in the global_config/ssl directory. For convenience in writing configuration, the Deployment Framework sets a configuration variable SSLCERT_PATH to this directory.

For a full list of Deployment Framework configuration variables, see Configuration macros and items.

Liberator’s direct SSL feature blade configures default key and certificate locations as follows:

Default key, passphrase, and certificate paths
File Configuration item Default value

Certificate

directssl-certificate

global_config/ssl/rttpd_https.pem

Private key

directssl-privatekey

global_config/ssl/rttpd_https.key

Private-key passphrase

directssl-passwordfile

global_config/ssl/rttpd_https.pwd

To override the default paths, assign new paths to directssl-certificate, directssl-privatekey, and directssl-passwordfile in the Deployment Framework file global_config/overrides/servers/Liberator/etc/rttpd.conf.

Deprecation of certificates with MD5- and SHA1-based digital signatures

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’s demonstration self-signed SSL certificate was re-issued with a SHA256-based digital signature in versions 6.2.23, 7.0.5, and 7.1.1 of Liberator. 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.

To determine the digital signature algorithm used in a certificate, use OpenSSL’s x509 command to read the certificate and then grep the output:

Determining the digital signature algorithm in certificate 'rttpd_https.pem'
$ openssl x509 -in rttpd_https.pem -text -noout | grep -m1 'Signature Algorithm'
    Signature Algorithm: sha256WithRSAEncryption
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

For the convenience of developers and software testers, Caplin ships a self-signed demonstration certificate with Liberator.

Do not use Caplin’s self-signed certificate in production.

In versions of the Deployment Framework prior to 7.0.2, the Deployment Framework automatically deploys Caplin’s self-signed certificate with Liberator if no keys and certificate exist for Liberator in the global_config/ssl directory.

From version 7.0.2 of the Deployment Framework, the Deployment Framework does not automatically deploy Caplin’s self-signed certificate with Liberator. To manually deploy the self-signed certificate, run the copy-ssl-demo-files Deployment Framework command:

./dfw copy-ssl-demo-files

When you first connect a web browser to a Liberator that presents Caplin’s self-signed certificate, your web browser will prompt you to trust the certificate.

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 Deprecation of certificates with MD5- and SHA1-based digital signatures above.

  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.

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

Configuring support for SSL/TLS protocols and ciphers

Maintaining Liberator’s list of permitted SSL/TLS protocols and ciphers should form part of your security policy. Industry best practices can change quickly, and you should regularly review your configuration under the guidance of security professionals.

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

SSL and TLS protocols enabled by default in Liberator
Liberator SSLv2 SSLv3 TLSv1 TLSv1.1 TLSv1.2

7.1.2

7.0.1

6.2.2

6.2.0

For the SSL and TLS ciphers supported by your version of Liberator, see the release notes to learn the version of OpenSSL bundled with your Liberator and then consult the OpenSSL documentation.

To configure protocol and cipher support for Liberator’s Direct SSL port, assign new values to the following configuration items in the Deployment Framework’s global_config/overrides/servers/Liberator/etc/rttpd.conf file:

Whichever SSL/TLS protocol versions you allow, ensure that you also allow ciphers appropriate for those protocol versions. If you disallow all ciphers supported by a protocol version, communication using that protocol version is impossible.

Guidance on choosing protocols and ciphers

Choosing which SSL/TLS protocols and ciphers to support is a balance between minimising security risk and supporting the broadest range of clients.

For introductory reading, follow the links below:

OpenSSL cipher list format

The directssl-cipher-list configuration item accepts a list of ciphers in OpenSSL cipher list format. For a description of the OpenSSL cipher list format, see Cipher List Format on the OpenSSL website.

To view how OpenSSL expands a cipher list to its individual ciphers, run the OpenSSL ciphers command on the cipher list:

Expanding the OpenSSL cipher list 'ECDHE:DHE:!SSLv3:!SSLv2:@STRENGTH'
$ openssl ciphers -v 'ECDHE:DHE:!SSLv3:!SSLv2:@STRENGTH' | column -t
ECDHE-ECDSA-AES256-GCM-SHA384   TLSv1.2  Kx=ECDH  Au=ECDSA  Enc=AESGCM(256)             Mac=AEAD
ECDHE-RSA-AES256-GCM-SHA384     TLSv1.2  Kx=ECDH  Au=RSA    Enc=AESGCM(256)             Mac=AEAD
ECDHE-ECDSA-CHACHA20-POLY1305   TLSv1.2  Kx=ECDH  Au=ECDSA  Enc=CHACHA20/POLY1305(256)  Mac=AEAD
ECDHE-RSA-CHACHA20-POLY1305     TLSv1.2  Kx=ECDH  Au=RSA    Enc=CHACHA20/POLY1305(256)  Mac=AEAD
... output truncated ...
For an accurate representation of how Liberator’s built-in OpenSSL expands a cipher string, run the above command with a version of OpenSSL equal to the version built into your Liberator. To determine the version of OpenSSL built into a Liberator binary, see OpenSSL.

Supplying parameters for ephemeral Diffie Hellman (DHE) ciphers

Ephemeral Diffie-Hellman (DHE) ciphers require a Diffie-Hellman (DH) parameter file. No DH parameter file is provided with Liberator; you must generate one manually. If you do not generate a DH parameter file, Liberator silently drops DHE ciphers from the list of ciphers you assign to directssl-cipher-list.

Example SSL/TLS protocol and cipher configuration

The configuration in this section is provided for illustrative purposes only and does not constitute security advice. You should test all security configuration and review its suitability for your security and business requirements before deploying to production.

The example below configures Liberator’s direct SSL interface to use TLS 1.2, TLS 1.1, and TLS 1.0 with forward secrecy ciphers ECDHE and DHE. When the equivalent configuration for Liberator’s HTTPS interface was tested on Liberator 7.1.2 using the SSL Labs Server Test on Sep 21 2018, the configuration scored A+. View the SSL Labs report.

TLS 1.2, TLS 1.1, and TLS 1.0 with ECDHE and DHE ciphers (requires DH parameter file)
directssl-ssl-options  SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1
directssl-cipher-list  ECDHE:DHE:!SSLv2:!SSLv3:@STRENGTH
directssl-dhparams     ${SSLCERT_PATH}/rttpd-dhparam-2048.pem

Enabling support for ephemeral Diffie-Hellman (DHE) ciphers

Ephemeral Diffie-Hellman ciphers (DHE) ciphers are supported by Liberator from version 6.2.14 and 7.0.1, but are not enabled by default.

DHE ciphers require a Diffie-Hellman (DH) parameter file. No parameter file is provided with Liberator; for security reasons, you must generate your own. If you do not generate a DH parameter file, Liberator silently removes DHE ciphers from the cipher list you assign to the directssl-cipher-list configuration item.

To generate a Diffie-Hellman (DH) parameters file, follow the steps 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 the Deployment Framework’s global_config/ssl/ directory.

  3. Assign the location of the DH parameters file to the directssl-dhparams configuration item in the Deployment Framework’s global_config/overrides/servers/Liberator/etc/rttpd.conf file:

    directssl-dhparams ${SSLCERT_PATH}/rttpd-dhparam-2048.pem
  4. Assign a cipher string containing DHE ciphers to the directssl-cipher-list configuration item.

  5. Restart Liberator

  6. Open a terminal and run the command below to test connecting to Liberator using a specific DHE cipher from your cipher list:

    openssl s_client -cipher cipher -connect host:port

    To view a list of all the DHE ciphers in your cipher list, run the OpenSSL command below:

    openssl ciphers -v cipher_list | column -t

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: