# HTTPS configuration
These Liberator configuration items define how Liberator handles secure HTTPS connections with clients.
Like Liberator’s HTTP interface, Liberator’s HTTPS interface is used to serve [RTTP](liberator-rttp.md) streaming traffic (see [StreamLink connection types](../streamlink/streamlink-connection-types.md)) and web pages from Liberator’s `htdocs` directory.
To enable HTTPS (and disable HTTP) in Liberator, see [Enabling HTTPS](liberator-configure-how-liberator-handles-https-connections.md#enabling-https).
## add-virtual-host
`add-virtual-host` defines a name-based or IP-based virtual host. Each virtual-host definition overrides some or all of the global configuration options [https-certificate](#https-certificate), [https-privatekey](#https-privatekey), [https-passwordfile](#https-passwordfile), [https-password](#https-password), [https-dhparams](liberator-https-configuration.md#https-dhparams), and [http_wwwroot](liberator-http-configuration-part-1.md#http-wwwroot) for a specific IP address or hostname.
Liberator supports the TLS extension Server Name Indication (SNI) for name-based virtual hosting over HTTPS. For more information on SNI, see [Server Name Indication](https://en.wikipedia.org/wiki/Server_Name_Indication).
To configure Liberator to present a different TLS certificate for each of the alternative hostnames by which a Liberator server is known, define an `add-virtual-host` block for each alternative hostname.
**Syntax:**
```
add-virtual-host
xref:name[name] [string]
xref:addr[addr] [string]
xref:add-virtual-host-https-certificate[https-certificate] [string]
xref:add-virtual-host-https-passwordfile[https-passwordfile] [string]
xref:add-virtual-host-https-password[https-password] [string]
xref:add-virtual-host-https-privatekey[https-privatekey] [string]
xref:add-virtual-host-https-dhparams[https-dhparams] [string]
xref:wwwroot[wwwroot] [string]
end-virtual-host
```
**Options for add-virtual-host**
| Options | Type | Default | Description |
| --- | --- | --- | --- |
| `addr` | string | +[none]+ | The IP address or hostname of this virtual host. From Liberator 8.0.1+, if the address is invalid, Liberator will fail to start. |
| `https-certificate` | string | Value of [https-certificate](#https-certificate) | The filename and directory path of the SSL (secure sockets layer) certificate used for HTTPS connections to this virtual host. The file must be in PEM format. The directory path is optional and can be in relative or absolute format. This option overrides for this virtual host the certificate filename and path defined in the global configuration item [https-certificate](#https-certificate). |
| `https-passwordfile` | string | Value of [https-passwordfile](#https-passwordfile) | The filename and directory path of the file containing the SSL certificate passphrase used for HTTPS connections to this virtual host. The file must be in PEM format. The directory path is optional and can be in relative or absolute format. This option overrides for this virtual host the password filename and path defined in the global configuration item [https-password](#https-password). |
| `https-password` | string | Value of [https-password](#https-password) | The passphrase used for HTTPS connections to this virtual host. This option overrides for this virtual host the password defined in the global configuration item [https-password](#https-password). If `https-password` is configured then it is used and any [https-passwordfile](#https-passwordfile) that is configured is ignored. |
| `https-privatekey` | string | Value of [https-privatekey](#https-privatekey) | The filename and directory path of the SSL (secure sockets layer) private key used for HTTPS connections to this virtual host. The file must be in PEM format. The directory path is optional and can be in relative or absolute format. This option overrides for this virtual host the private key filename and path defined in the global configuration item [https-privatekey](#https-privatekey). |
| `https-dhparams` | string | +[none]+ | The path to a Diffie-Hellman (DH) parameters file, which is required by ephemeral Diffie-Hellman ciphers (DHE). For instructions on how to generate a DH parameters file, see [Additional requirements ephemeral Diffie-Hellman ciphers](liberator-configure-how-liberator-handles-https-connections.md#dhparam). This option overrides for this virtual host the path to the DH parameters file defined in the global configuration item [https-dhparams](liberator-https-configuration.md#https-dhparams). |
| `name` | string | Value of the [addr](#addr) option | A name for this virtual host. |
| `wwwroot` | string | Value of [http-wwwroot](liberator-http-configuration-part-1.md#http-wwwroot) | The root directory of the Liberator’s HTML files for this virtual host. The directory path can contain the parameter `%r`, which is replaced at run time by the root directory ([application-root](../datasource/datasource-run-time-environment-configuration.md#application-root)) under which the Liberator runs. This option overrides for this virtual host the root directory defined in the global configuration item [http-wwwroot](liberator-http-configuration-part-1.md#http-wwwroot). |
**Example:**
In this example, a Liberator server, `host1.example.com`, also has DNS entries for the host names `host2.example.com` and `host3.example.com` at the same IP address. The example configuration below uses `add-virtual-host` blocks to define the TLS certificates to use for `host1.example.com` and `host2.example.com`.
```
# TLS certificate for host2.example.com
add-virtual-host
addr host2.example.com
https-certificate ${SSLCERT_PATH}/host2.example.com.cert.pem
https-privatekey ${SSLCERT_PATH}/host2.example.com.key.pem
https-passwordfile ${SSLCERT_PATH}/host2.example.com.key.pwd
end-virtual-host
# TLS certificate for host3.example.com
add-virtual-host
addr host3.example.com
https-certificate ${SSLCERT_PATH}/host3.example.com.cert.pem
https-privatekey ${SSLCERT_PATH}/host3.example.com.key.pem
https-passwordfile ${SSLCERT_PATH}/host3.example.com.key.pwd
end-virtual-host
```
## https-certificate
`https-certificate` specifies the filename and directory path of the SSL (secure sockets layer) certificate used for HTTPS connections. This file must be in PEM format. The directory path is optional and can be in relative or absolute format.
This item is overridden for specific virtual host connections by the [https-certificate](#add-virtual-host-https-certificate) option of the [add-virtual-host](#add-virtual-host) that defines the virtual host.
For more information on setting `https-certificate`, see [Installing keys and certificates](liberator-configure-how-liberator-handles-https-connections.md#installing-keys-and-certificates).
The default value for `https-certificate` is the same as the default value for [https-privatekey](#https-privatekey) because both the certificate and the private key can be contained in the same file.
**Syntax:** `https-certificate `
**Type:** string
**Default value:** `cert.pem`
## https-ciphersuites (TLS 1.3)
`https-ciphersuites` specifies the TLS 1.3 ciphers supported by Liberator’s HTTPS interface, formatted as an [OpenSSL cipher list](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT). To set the TLS 1.0–1.2 ciphers supported by Liberator, see [https-cipher-list](#https-cipher-list).
This is an advanced TLS 1.3 configuration option for specific use cases only. You do not need to set this option to enable TLS 1.3 support in Liberator. TLS 1.3 support is enabled by default from Liberator 7.1.5.
When `https-ciphersuites` is not specified, Liberator uses OpenSSL’s default TLS 1.3 cipher list.
In accordance with the TLS specification, Liberator ignores the priority order of ciphers in `https-ciphersuites` and favours the TLS _client’s_ cipher priority order. To reverse this default behaviour, set the `SSL_OP_CIPHER_SERVER_PREFERENCE` flag in [https-ssl-options](#https-ssl-options). To log the cipher lists of connecting clients, see [https-log-hello-ciphers](#https-log-hello-ciphers).
**Since:** Liberator 7.1.25
**Syntax:** `https-ciphersuites <[openssl_cipher_list](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT)>`
**Type:** string
**Default value**: _OpenSSL default_
## https-cipher-list
`https-cipher-list` specifies the TLS 1.0–1.2 ciphers supported by Liberator’s HTTPS interface, formatted as an [OpenSSL cipher list](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT).
In accordance with the TLS specification, when choosing a cipher for a connection, Liberator chooses the client’s most preferred cipher from among the ciphers they have in common. To reverse this default behaviour, set the `SSL_OP_CIPHER_SERVER_PREFERENCE` flag in [https-ssl-options](#https-ssl-options). To define Liberator’s cipher preference, order ciphers in `https-cipher-list` in descending order of preference, most preferred cipher first.
To log the cipher lists of connecting TLS clients, see [https-log-hello-ciphers](#https-log-hello-ciphers).
Configure this item in conjunction with [https-ssl-options](#https-ssl-options) (SSL/TLS protocol versions) and [https-dhparams](#https-dhparams) (required for DHE ciphers).
**❗ IMPORTANT**\
The default TLS configuration is not a security recommendation and is not updated regularly. Review the values for [https-cipher-list](#https-cipher-list), [https-ssl-options](#https-ssl-options), and [https-dhparams](#https-dhparams) for compliance with your security policy before deploying Liberator to production, and review regularly thereafter.
For detailed information on how to set ciphers for Liberator’s HTTPS interface, see [Configuring supported TLS ciphers](liberator-configure-how-liberator-handles-https-connections.md#ciphers).
**Syntax:** `https-cipher-list <[openssl_cipher_list](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT)>`
**Type:** string
**Default value**:
* **Liberator 7.1.25:** `TLSv1.2+ECDHE+AESGCM:TLSv1.2+ECDHE+AESCCM:TLSv1.2+ECDHE+CHACHA20:TLSv1.2+DHE+AESGCM:TLSv1.2+DHE+AESCCM:TLSv1.2+DHE+CHACHA20`
* **Liberator 7.1.5:** `ECDHE:DHE:!SSLv3:!SSLv2:@STRENGTH`
* **Liberator 7.0:** `DEFAULT:!RC4-SHA:!RC4-MD5:!DES-CBC3-SHA`
* **Liberator 6.0:** `DEFAULT`
**Examples:** See [Configuring supported TLS ciphers](liberator-configure-how-liberator-handles-https-connections.md#ciphers)
## https-dhparams
`https-dhparams` specifies the path to a Diffie-Hellman (DH) parameters file, which is required by ephemeral Diffie-Hellman ciphers (DHE).
Configure this item in conjunction with [https-ssl-options](#https-ssl-options) (SSL/TLS protocol versions) and [https-cipher-list](#https-cipher-list) (SSL/TLS ciphers).
**❗ IMPORTANT**\
The default TLS configuration is not a security recommendation and is not updated regularly. Review the values for [https-cipher-list](#https-cipher-list), [https-ssl-options](#https-ssl-options), and [https-dhparams](#https-dhparams) for compliance with your security policy before deploying Liberator to production, and review regularly thereafter.
For instructions on how to generate a DH parameters file, see [Generating a Diffie-Hellman parameters file for DHE ciphers](liberator-configure-how-liberator-handles-https-connections.md#dhparam).
**Availability:** Liberator 6.2.14+, Liberator 7.0.1+
**Syntax:** `https-dhparams `
**Type:** string
**Default value:** <empty string>
**Example:**
```
https-dhparams ${SSLCERT_PATH}/rttpd-dhparam-2048.pem
```
## https-disable-renegotiation
`https-disable-renegotiation` when set to `TRUE`, prevents clients from renegotiating their HTTPS connections. This protects against Denial of Service attacks involving repeated attempts to renegotiate.
**Syntax:** `https-disable-renegotiation `
**Type:** boolean
**Default value:** `FALSE` (Liberator 6.2), `TRUE` (Liberator 7)
## https-enable
`https-enable` switches on support for HTTPS connections when set to `TRUE`.
**Syntax:** `https-enable `
**Type:** boolean
**Default value:** `FALSE` (HTTPS connections not supported)
## https-interface
`https-interface` specifies the network interfaces to listen on for HTTPS connection requests.
For a Liberator deployed within a Caplin Deployment Framework, `https-interface` is normally set indirectly by specifying a value for the Deployment Framework configuration macro `LIBERATOR${THIS_LEG}_HTTPSINTERFACE`. Only one HTTPS interface can be specified in the macro; to add extra interfaces, append new `https-interface` items to the configuration override file `/global_config/overrides/servers/Liberator/etc/rttpd.conf`.
This configuration item supports IPv6 addresses from version 7 of Liberator, and multiple address wildcards from version 7.0.2.
**Wildcard support**
| Configuration | Liberator 6.2 | Liberator 7.0 |
| --- | --- | --- |
| `https-interface` | **Default**. A single IPv4 server socket that listens on all IPv4 interface addresses. | **Default**. A single IPv6 server socket that accepts IPv4-mapped addresses and that listens on all IPv6 and IPv4 interface addresses. |
| `https-interface *` | A single IPv4 server socket that listens on all IPv4 interface addresses. | A single IPv6 server socket that accepts IPv4-mapped addresses and that listens on all IPv6 and IPv4 interface addresses. |
| `https-interface 0.0.0.0` | A single IPv4 server socket that listens on all IPv4 interface addresses. | A single IPv4 server socket that listens on all IPv4 interface addresses. |
| `https-interface ::` | _Not supported_ | A single IPv6 server socket that listens on all IPv6 interface addresses. |
| `https-interface 0.0.0.0 ::` | _Not supported_ | A single IPv4 server socket that listens on all IPv4 interface addresses, and a single IPv6 server socket that listens on all IPv6 interface addresses. NOTE: Supported from Liberator 7.0.2 |
**💡 TIP**\
To configure Liberator’s HTTPS server to listen on all its host’s IPv4 and IPv6 addresses, use `https-interface 0.0.0.0 ::` in preference to relying on the default setting. The default setting is less resilient than specifying separate IPv4 and IPv6 wild cards because IPv4-to-IPv6 address mapping can be disabled by a system administrator at the operating system level.
**Syntax:** `https-interface ...`
**Type:** array of strings
**Default value:** +[all available network interfaces]+
## https-log-hello-ciphers
Enables logging of the cipher list presented by TLS clients in the TLS handshake with Liberator.
From Liberator 7.1.25, client cipher lists are logged at INFO level and require the `SSL.Detail` log category to be enabled (see [`log-category-filter`](../datasource/datasource-logging-configuration.md#log-category-filter)):
```
https-log-hello-ciphers
log-category-filter SSL.Detail
```
For Liberator 7.1.23 and 7.1.24, client cipher lists for successful connections are logged at DEBUG level. Client cipher lists for unsuccessful connections are logged at INFO level.
**Since:** Liberator 7.1.23
**Syntax:** `https-log-hello-ciphers `
**Type:** boolean
**Default value:** FALSE
## https-passwordfile
`https-passwordfile` specifies the filename and directory path of the file containing the passphrase for the encrypted SSL/TLS key used for HTTPS connections (see [https-privatekey](#https-privatekey)). The directory path is optional and can be in relative or absolute format.
This item is overridden for specific virtual host connections by the [https-passwordfile](#add-virtual-host-https-passwordfile) option of the [add-virtual-host](#add-virtual-host) that defines the virtual host.
If the TLS key is unencrypted, then the password file must be empty.
**From Liberator 7.1.9**: If the TLS key is unencrypted and you don’t want to deploy an empty password file, then set the configuration variable [`HTTPS_PASSWORD_FILE_REQUIRED`](../deployment-framework/cdf-configuration-macros-and-items.md#https-password-file-required) to `NO` in the Deployment Framework file `global_config/environment.conf`.
For more information on setting `http-passwordfile`, see [Installing keys and certificates](liberator-configure-how-liberator-handles-https-connections.md#installing-keys-and-certificates).
**Syntax:** `https-passwordfile `
**Type:** string
**Default value:** `rttpd_https.pwd`
## https-password
`https-password` specifies the passphrase for the encrypted SSL/TLS key used for HTTPS connections (see [https-privatekey](#https-privatekey)).
This item is overridden for specific virtual host connections by the [https-password](#add-virtual-host-https-password) option of the [add-virtual-host](#add-virtual-host) that defines the virtual host.
If the TLS key is unencrypted, then the password should not be configured.
For more information on setting `http-password`, see [Installing keys and certificates](liberator-configure-how-liberator-handles-https-connections.md#installing-keys-and-certificates).
**Since:** Liberator 8.0.7
**Syntax:** `https-password `
**Type:** string
**Default value:** None
💡 TIP
If you have saved your password in an environment variable then you can use this configuration item to allow the Liberator to access it. For example if your password is in the environment variable `MYPASSWORD`, then use the configuration below:
```
https-password ${ENV:MYPASSWORD}
```
## https-port
`https-port` specifies the network port that Liberator listens on for HTTPS connection requests.
**📌 NOTE**\
In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), a configuration variable `LIBERATOR${THIS_LEG}_HTTPSPORT` is used to specify Liberator’s `https-port`. See [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md) and How can I ... [Configure how Liberator handles HTTPS connections](liberator-configure-how-liberator-handles-https-connections.md).
**Syntax:** `https-port `
**Type:** integer
**Default value:** `4443`
## https-privatekey
`https-privatekey` specifies the filename and directory path of the SSL (secure sockets layer) private key used for HTTPS connections. This file must be in PEM format. The directory path is optional and can be in relative or absolute format.
This item is overridden for specific virtual host connections by the [https-privatekey](#add-virtual-host-https-privatekey) option of the [add-virtual-host](#add-virtual-host) that defines the virtual host.
For information on setting the private key, see [Installing keys and certificates](liberator-configure-how-liberator-handles-https-connections.md#installing-keys-and-certificates).
The default value of `https-privatekey` is the same as the default for [https-certificate](#https-certificate) because both the certificate and the private key can be contained in the same file.
**Syntax:** `https-privatekey `
**Type:** string
**Default value:** `cert.pem`
## https-ssl-options
`https-ssl-options` configures the SSL/TLS protocols accepted by Liberator’s HTTPS interface.
Configure this item in conjunction with [https-cipher-list](#https-cipher-list) (SSL/TLS ciphers) and [https-dhparams](#https-dhparams) (required for DHE ciphers).
**❗ IMPORTANT**\
The default TLS configuration is not a security recommendation and is not updated regularly. Review the values for [https-cipher-list](#https-cipher-list), [https-ssl-options](#https-ssl-options), and [https-dhparams](#https-dhparams) for compliance with your security policy before deploying Liberator to production, and review regularly thereafter.
Use `https-ssl-options` to disable support for older versions of SSL, and to enable workarounds for known bugs in client implementations of SSL.
This configuration item takes one parameter: a pipe-separated list of OpenSSL options from the table below.
**Supported OpenSSL options**
| Option | Description |
| --- | --- |
| `SSL_OP_ALL` | Enable all of OpenSSL’s workarounds for known bugs in client implementations of SSL. For the full list of workarounds enabled by this option, see [SSL_CTX_set_options](https://docs.openssl.org/1.1.1/man3/SSL_CTX_set_options/) on the OpenSSL website. |
| `SSL_OP_NO_SSLv2` | Disable support for SSL 2. |
| `SSL_OP_NO_SSLv3` | Disable support for SSL 3. |
| `SSL_OP_NO_TLSv1` | Disable support for TLS 1. |
| `SSL_OP_NO_TLSv1_1` | Disable support for TLS 1.1. Available from Liberator 6.2.2. |
| `SSL_OP_NO_TLSv1_2` | Disable support for TLS 1.2. Available from Liberator 6.2.2. |
| `SSL_OP_NO_TLSv1_3` | Disable support for TLS 1.3. Available from Liberator 7.1.5. |
| `SSL_OP_CIPHER_SERVER_PREFERENCE` | In a TLS handshake, the TLS client presents Liberator with a list of the ciphers it supports in priority order, and Liberator chooses a cipher from the list. By default, and in accordance with the TLS specification, Liberator chooses the client’s most preferred cipher from the ciphers they have in common. When `SSL_OP_CIPHER_SERVER_PREFERENCE` is set, Liberator chooses its most preferred cipher from the ciphers they have in common. This breaks with the TLS specification. Liberator’s cipher preferences are determined by the order of ciphers in [`https-cipher-list`](#https-cipher-list) and [`directssl-cipher-list`](liberator-direct-connections-configuration.md#directssl-cipher-list). Ciphers are listed in descending order of preference, most preferred cipher first. Available from Liberator 7.1.25. |
For more information on setting TLS protocol versions for Liberator’s HTTPS interface, see [Configuring supported TLS protocol versions](liberator-configure-how-liberator-handles-https-connections.md#protocol-versions).
**Syntax:** `https-ssl-options