# HTTPS configuration These Liberator configuration items define how Liberator handles HTTPS connections with clients. The Secure Sockets Layer (SSL) is a commonly-used protocol for managing the security of message transmission on the Internet, and offers a greater level of protection than standard HTTP transmission. Web pages and other standard HTTP traffic can be sent over HTTPS. Liberator can run as an HTTPS web server like most commonly available web servers. When it’s configured to use HTTPS, all [RTTP](liberator-rttp.md) data is sent over an HTTPS connection too, which means your streaming data and trade transactions are secure. Liberator supports standard SSL server-side certificates to authenticate the server to the client. The certificates must be generated and signed by a certificate authority. **💡 TIP**\ Liberator’s supplied with a built-in HTTPS [Config blade](../deployment-framework/cdf-blade-types.md) (see [Built-in blades](../deployment-framework/cdf-built-in-blades.md)) that you activate to enable HTTPS connections. For details on how to do this and how to change the blade’s configuration, see How can I... [Configure how Liberator handles HTTPS connections](liberator-configure-how-liberator-handles-https-connections.md). **💡 TIP**\ You may also need to set [ssl-random-seed](../datasource/datasource-datasource-secure-sockets-layer-ssl-configuration.md#ssl-random-seed), which configures the seeding of the [OpenSSL](https://www.openssl.org) random number generator that the Liberator uses for HTTPS and direct secure connections. ## add-virtual-host `add-virtual-host` specifies a virtual host that Liberator will serve. Virtual hosts allow a single Liberator to serve separate (independent) websites. `add-virtual-host` provides a simple method for defining virtual hosts within Liberator, but it does require the Liberator to have a separate IP address for each host. Liberator versions 6.1 and above support virtual hosting using Server Name Indication (SNI), which allows a single IP address to serve a group of domain names, providing a separate SSL certificate for each name. If you want Liberator to serve multiple websites securely, we recommend that you do this using SNI rather than `add-virtual-host`. For more about SNI, see the Wikipedia page at [https://en.wikipedia.org/wiki/Server_Name_Indication](https://en.wikipedia.org/wiki/Server_Name_Indication). You can use `add-virtual-host` to configure the following aspects of a virtual host: * The directory to use as the root directory for the website (option [wwwroot](#wwwroot)). * The SSL certificate, password and private key files to use for HTTPS connections (options [https-certificate](#https-certificate), [https-passwordfile](#https-passwordfile) and [https-privatekey](#https-privatekey)). When a client connects to Liberator through an IP address or hostname that’s identified by the [addr](#addr) option of an `add-virtual-host` configuration item, Liberator applies the option settings of the `add-virtual-host` to that particular connection. **📌 NOTE**\ Each virtual host is defined by the _IP address_ the client connects to, and not by HTTP 1.1’s _name-based_ virtual host facility. **Syntax:** (Click on an option to see its description in the table below.) ``` 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-privatekey[https-privatekey] [string] xref:wwwroot[wwwroot] [string] end-virtual-host ``` The options for `add-virtual-host` are: | Name | Type | Default | Description | | --- | --- | --- | --- | | `addr` | string | +[none]+ | The local IP address or hostname of this virtual host. | | `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-passwordfile](#https-passwordfile). | | `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). | | `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). | ## 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 overidden 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.
đź“Ś NOTE
In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), a configuration macro `SSLCERT_PATH` is used to specify the directory path in the Liberator’s `https-certificate` setting. See [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md). The certificate filename and path set up by default in the Liberator supplied with the Framework is _<Framework-root>/global_config/ssl/rttpd_https.pem_ This certificate file is shared between HTTPS and Direct SSL connections. Liberator is supplied with an _rttpd_https.pem_ file that’s automatically copied to _<Framework-root>/global_config/ssl/_ when you deploy the Liberator to the Framework, unless you’ve previously put your own version of this file in the directory.
**Syntax:** `https-certificate ` **Type:** string **Default value:** `cert.pem` The default filename for the certificate is the same as the private key’s default filename (default for [https-privatekey](#https-privatekey)) because both the certificate and the private key can be contained in the same file. ## https-cipher-list `https-cipher-list` specifes a colon separated list of cipher strings. These cipher strings select, in preferred order, the various SSL ciphers (cryptographic algorithms) that Liberator can use for its HTTPS connections. The ciphers are selected from the set available in the version of [OpenSSL](https://www.openssl.org) built into Liberator. The format of the cipher list is as defined for the `cipherlist` argument of the OpenSSL `ciphers` tool; for details see the OpenSSL 1.0.2 `ciphers(1)` manual page, which includes a list of the available cipher suite names. At run time, Liberator passes the cipher list as a control string to the OpenSSL 1.0.2 function `SSL_CTX_set_cipher_list()`; this function uses the control string to set up the list of available SSL ciphers. **Syntax:** `https-cipher-list ::...` **Type:** string **Default value:** `DEFAULT` (The default list of OpenSSL ciphers. This may vary according to the version of OpenSSL built into Liberator.) **Example:** ``` https-cipher-list HIGH:MEDIUM ``` ## 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` (client renegotiation is allowed) ## 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. **📌 NOTE**\ In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), a configuration macro `LIBERATOR${THIS_LEG}_HTTPINTERFACE` is used to specify Liberator’s `https-interface`. 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-interface ` **Type:** array of strings **Default value:** +[all available network interfaces]+ ## https-passwordfile `https-passwordfile` specifies the filename and directory path of the file containing the SSL certificate passphrase used for HTTPS connections. The directory path is optional and can be in relative or absolute format. This item is overidden 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. **📌 NOTE**\ In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), a configuration macro `SSLCERT_PATH` is used to specify the directory path in the Liberator’s `https-passwordfile` setting. See [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md). The password filename and path set up by default in the Liberator supplied with the Framework is _<Framework-root>/global_config/ssl/rttpd_https.pwd_ This password file is shared between HTTPS and Direct SSL connections. Liberator is supplied with an _rttpd_https.pwd_ file that’s automatically copied to _<Framework-root>/global_config/ssl/_ when you deploy the Liberator to the Framework, unless you’ve previously put your own version of this file in the directory. **Syntax:** `https-passwordfile ` **Type:** string **Default value:** `rttpd.https.pass` ## 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 macro `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 overidden 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. **📌 NOTE**\ In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), a configuration macro `SSLCERT_PATH` is used to specify the directory path in the Liberator’s `https-privatekey` setting. See [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md). The key filename and path set up by default in the Liberator supplied with the Framework is _<Framework-root>/global_config/ssl/rttpd_https.key_ This private key file is shared between HTTPS and Direct SSL connections. Liberator is supplied with an _rttpd_https.key_ file that’s automatically copied to _<Framework-root>/global_config/ssl/_ when you deploy the Liberator to the Framework, unless you’ve previously put your own version of this file in the directory. **Syntax:** `https-privatekey ` **Type:** string **Default value:** `cert.pem` The default filename for the private key is the same as the certificate’s default filename (default for [https-certificate](#https-certificate)) because both the certificate and the private key can be contained in the same file. ## https-ssl-options `https-ssl-options` changes the protocols supported by the OpenSSL library packaged with Liberator. Use `https-ssl-options` to disable support for older versions of SSL, and to enable workarounds for known bugs in client implementations of SSL. **Syntax:** `https-ssl-options ` **Type:** string **Default value:** `SSL_OP_NO_SSLv2` **Values accepted:** | VALUE | MEANING | | --- | --- | | `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 the OpenSSL 1.0.2 documentation for `SSL_CTX_set_options`. | | `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 | | `SSL_OP_NO_TLSv1_2` | Disable support for TLS 1.2 | You can combine multiple values using the bitwise `|` operator. The example below disables support for SSLv2 and SSLv3, ensuring all connections are protected by at least TLSv1: ``` https-ssl-options SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3 ``` ## ssl-random-seed See [ssl-random-seed](../datasource/datasource-datasource-secure-sockets-layer-ssl-configuration.md#ssl-random-seed) in [DataSource Secure Sockets Layer (SSL) configuration](../datasource/datasource-datasource-secure-sockets-layer-ssl-configuration.md). --- **See also:** * How can I... [Configure how Liberator handles HTTPS connections](liberator-configure-how-liberator-handles-https-connections.md) * Reference: [HTTP configuration](liberator-http-configuration-part-1.md)