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.
|
- Liberator’s SSL/TLS implementation
- Enabling HTTPS
- Configuring the HTTPS port
- Configuring the HTTPS interface
- Installing keys and certificates
- Configuring SSL/TLS protocols and ciphers
- Generating a Diffie-Hellman parameters file for DHE ciphers
- Seeding the OpenSSL random number generator
- Configuring OpenSSL
Liberator’s SSL/TLS implementation
Liberator uses OpenSSL to provide its implementation of SSL/TLS. The OpenSSL library is built-in to Liberator and is independent of the host system’s installation of OpenSSL.
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 '^openssl [0-9]'
Enabling HTTPS
Liberator’s default HTTP and HTTPS configuration is provided in two feature blades ( config blades): HTTP
and HTTPS
.
The HTTP feature blade is activated by default.
To deactivate HTTP and activate HTTPS, follow the steps below:
-
Run the commands below to deactivate the HTTP blade and activate the HTTPS blade:
./dfw deactivate HTTP ./dfw activate HTTPS
-
Review the default HTTPS port and interface. See Configuring the HTTPS port and Configuring the HTTPS interface.
-
Install an SSL/TLS key, password file, and certificate. See Installing keys and certificates.
-
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 SSL/TLS protocols and ciphers.
-
Generate a Diffie-Hellman (DH) parameters file to allow Liberator to use ephemeral Diffie-Hellman (DHE) ciphers. See Generating a Diffie-Hellman parameters file for DHE ciphers.
-
If this is a production server, disable Liberator’s built-in administrator website:
./dfw deactivate LiberatorWebsite ./dfw activate MinimalLiberatorWebsite
-
If this is a production server, enable SSL/TLS for Liberator’s direct RTTP interface, or disable the direct RTTP interface entirely. See Configure how Liberator handles direct client connections for more information.
Configuring the HTTPS port
By default, Liberator’s HTTPS port is 18081. To change the HTTPS port, redefine the LIBERATOR${THIS_LEG}_HTTPSPORT
configuration variable in the <Framework-root>/global_config/environment.conf
file:
define LIBERATOR${THIS_LEG}_HTTPSPORT 443
Do not set the value of the https-port configuration item directly. Redefine the LIBERATOR${THIS_LEG}_HTTPSPORT configuration variable instead.
|
Configuring the HTTPS interface
By default, Liberator’s HTTP and HTTPS server sockets are bound to all network interfaces on Liberator’s host. To bind Liberator’s HTTP and HTTPS server sockets to one or more network interfaces, redefine the LIBERATOR${THIS_LEG}_HTTPINTERFACE
configuration variable in the <Framework-root>/global_config/environment.conf
file:
define LIBERATOR${THIS_LEG}_HTTPINTERFACE 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}_HTTPINTERFACE
variable implying that it applies only to HTTP server sockets, the variable applies to both HTTP and HTTPS server sockets.
Do not set the value of the https-interface configuration item directly. Redefine the LIBERATOR${THIS_LEG}_HTTPINTERFACE 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 HTTPS feature blade configures default key and certificate locations as follows:
File | Configuration item | Default value |
---|---|---|
Certificate |
|
|
Private key |
|
|
Private-key passphrase |
|
To override the default paths, assign new values to the https-certificate, https-privatekey, and https-passwordfile configuration items 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:
$ openssl x509 -in rttpd_https.pem -text -noout | grep -m1 'Signature Algorithm'
Signature Algorithm: sha256WithRSAEncryption
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:
-
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.
-
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
, andrttpd_https.pwd
.If you don’t want to use Liberator’s default file names, assign your own file names to the configuration items https-certificate, https-privatekey, and https-passwordfile in the file
global_config/overrides/servers/Liberator/etc/rttpd.conf
. -
Copy the private key, certificate, and password files to the <Framework-root>/global_config/ssl/ directory.
If the private key is unencrypted, the password file must be empty.
From Liberator 7.1.9: If the private key is unencrypted and you don’t want to deploy an empty password file, then set the configuration variable HTTPS_PASSWORD_FILE_REQUIRED
to NO
in the Deployment Framework file global_config/environment.conf
.
Configuring SSL/TLS protocols and ciphers
Liberator’s default TLS protocol and cipher configuration is balanced in favour of supporting as wide a range of web browser versions as possible. The default configuration is not updated regularly.
Review the configuration of Liberator’s SSL/TLS protocols and ciphers for compliance with your security policy before deploying Liberator to production, and regularly review the configuration thereafter. |
Liberator defaults
Liberator’s default TLS configuration is balanced in favour of supporting as wide a range of web browser versions as possible, with older browser versions supported at the cost of enabling deprecated TLS protocols. The default TLS configuration is not updated regularly and is for your initial convenience only; it is not a security recommendation.
If your Liberator does not need to support older web browsers, then disable Liberator’s support for all protocols older than TLS 1.2 and their associated ciphers. For example configuration, see Example TLS protocol and cipher configuration. |
All protocols supported by the version of OpenSSL included with Liberator are enabled unless explicitly disabled by https-ssl-options.
Liberator | SSL 2 * | SSL 3 † | TLS 1.0 ‡ | TLS 1.1 ‡ | TLS 1.2 | TLS 1.3 |
---|---|---|---|---|---|---|
7.1.5 |
- |
|||||
7.1.2 |
- |
- |
||||
7.0.1 |
- |
|||||
6.2.2 |
- |
|||||
6.2.0 |
- |
- |
- |
- Protocol not available
Protocol disabled (see https-ssl-options)
Protocol enabled
* The IETF prohibited SSL 2 in March 2011: RFC 6176
† The IETF deprecated SSL 3 in June 2015: RFC 7568
‡ The IETF recommended TLS 1.0 and TLS 1.1 for deprecation in June 2018: Deprecating TLSv1.0 and TLSv1.1
Liberator | Cipher string |
---|---|
7.1.5 * |
|
7.0.1 |
|
6.0.0 |
|
* From Liberator 7.1.5, only cipher suites that support forward secrecy (ECDHE and DHE) are enabled by default. DHE ciphers require a Diffie-Hellman parameters file, which is not distributed with Liberator (see Generating a Diffie-Hellman parameters file for DHE ciphers).
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 guidance on choosing protocols and ciphers, read the third-party resources below:
Configuring TLS protocol support
To configure the SSL/TLS protocols supported by Liberator, set the value of the https-ssl-options
configuration item.
For guidance on choosing which protocols to support, read the third party resources listed in Guidance on choosing protocols and ciphers above.
For example https-ssl-options
configuration, see Example TLS protocol and cipher configuration below.
Configuring TLS cipher support
To configure the SSL/TLS ciphers supported by Liberator, set the value of the https-cipher-list
configuration item.
For guidance on choosing which ciphers to support, read the third party resources listed in Guidance on choosing protocols and ciphers above.
The https-cipher-list configuration item accepts a list of ciphers in OpenSSL cipher list format. For a detailed description of the format, see Cipher List Format on the OpenSSL website.
If your cipher list includes Ephemeral Diffie-Hellman (DHE) ciphers, you must configure the https-dhparams
configuration item with the location of a valid Diffie-Hellman (DH) parameters file. If you fail to do so, Liberator silently drops DHE ciphers from its list of supported ciphers. See Generating a Diffie-Hellman parameters file for DHE ciphers.
To view how OpenSSL expands a cipher list to individual ciphers, run the OpenSSL Expand the cipher list 'ECDHE+TLSv1.2:DHE+TLSv1.2:@STRENGTH'
openssl ciphers -v 'ECDHE+TLSv1.2:DHE+TLSv1.2:@STRENGTH' | column -t |
For example https-cipher-list
configuration, see Example TLS protocol and cipher configuration below.
Example TLS protocol and cipher configuration
The configuration in this section is provided for illustrative purposes only, is not updated regularly, and does not constitute security advice. Review all TLS configuration before deploying to production, and schedule regular reviews thereafter. |
This example supports modern web clients (defined as all clients with support for TLS 1.2 and above).
Features:
-
TLS protocols: TLS 1.2, TLS 1.3 (Liberator supports TLS 1.3 from Liberator 7.1.5)
-
TLS ciphers: Forward-secrecy ciphers only (ECDHE, DHE). Weak ciphers removed. Ciphers ordered by strength.
-
Diffie-Hellman parameters: 2048-bit
When tested with Liberator 7.1.12 using the SSL Labs Server Test on 27 Apr 2020, the configuration below scored A+. View the SSL Labs report.
While the configuration below achieved an SSL Labs score of A+ on 27 Apr 2020, ciphers may weaken over time and the configuration may not achieve that score today. Retest and review this configuration before considering deploying it to production. |
# Disable TLS versions SSLv2, SSLv3, TLSv1, and TLSv1.1 # (retain TLSv1.2 and TLSv1.3) https-ssl-options SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1|SSL_OP_NO_TLSv1_1 # OpenSSL ciphers to include define CIPHER_INCLUDES "ECDHE+TLSv1.2:DHE+TLSv1.2" # OpenSSL ciphers to exclude define CIPHER_EXCLUDES "!CAMELLIA:!DHE-RSA-AES128-SHA256:!ECDHE-RSA-AES128-SHA256:!DHE-RSA-AES256-SHA256:!ECDHE-RSA-AES256-SHA384" # Set OpenSSL cipher string, and order ciphers by strength https-cipher-list ${CIPHER_INCLUDES}:${CIPHER_EXCLUDES}:@STRENGTH # Diffie-Hellman parameters file (for DHE ciphers) https-dhparams ${SSLCERT_PATH}/rttpd-dhparam-2048.pem
Generating a Diffie-Hellman parameters file for DHE ciphers
Ephemeral Diffie-Hellman ciphers (DHE) ciphers are supported by Liberator from version 6.2.14 and 7.0.1.
DHE ciphers require a Diffie-Hellman (DH) parameter file. If you do not configure the https-dhparams
configuration item with the location of a valid DH parameters file, Liberator silently removes DHE ciphers from its list of supported ciphers.
No DH parameters file is provided with Liberator; you must generate your own.
To generate a Diffie-Hellman (DH) parameters file, follow the steps below:
-
In the Deployment Framework’s
global_config/ssl/
directory, run the command below:openssl dhparam -out rttpd-dhparam-2048.pem 2048
This command can take a long time to complete.
-
Assign the location of the DH parameters file to the https-dhparams configuration item in the Deployment Framework’s
global_config/overrides/servers/Liberator/etc/rttpd.conf
file:https-dhparams ${SSLCERT_PATH}/rttpd-dhparam-2048.pem
To test that a Liberator supports DHE ciphers, follow the steps below:
-
In the file
global_config/overrides/servers/Liberator/rttpd.conf
, assign a cipher string containing DHE ciphers to thehttps-cipher-list
configuration item. For example:https-cipher-list ECDHE+TLSv1.2:DHE+TLSv1.2:@STRENGTH
-
Restart Liberator
-
Run the command below to test connecting to Liberator using a DHE cipher. The example below tests connecting with the DHE-DSS-AES256-GCM-SHA384 cipher, one of the DHE ciphers included in OpenSSL’s TLS 1.2 cipher suite:
openssl s_client -cipher DHE-DSS-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:
-
How can I… Configure how Liberator handles HTTP connections
-
How can I… Configure how Liberator handles direct client connections
-
How can I… Set up secure connections between DataSource applications
-
Reference: HTTPS configuration
-
Reference: HTTP configuration