# DataSource Secure Sockets Layer (SSL) configuration These DataSource configuration items enable you to set up secure communication between DataSource peers using the Secure Sockets Layer (SSL) of TCP/IP. C-based DataSource applications implement SSL using [OpenSSL](https://www.openssl.org/), and the security certificate and private key are kept in separate PEM files (see [datasrc-ssl-certificate](#datasrc-ssl-certificate) and [datasrc-ssl-privatekey](#datasrc-ssl-privatekey)). Java-based DataSource applications use the Java Cryptography APIs, and a Java KeyStore (JKS) to hold the security certificate and private key (see [datasrc-ssl-keystore](#datasrc-ssl-keystore)). The KeyStore can be accessed using an alias (see [datasrc-ssl-certificate](#datasrc-ssl-certificate)). The configuration items on this page apply to DataSource 6.2 and higher. For earlier DataSource versions, see section 12.8 "Direct connections using SSL" in the [Liberator 6.0 Administration Guide](https://docs.caplin.com/developer/docs/Liberator60AdminGuide.pdf). ## datasrc-ssl-enable Set `datasrc-ssl-enable` to `TRUE` to enable this DataSource to _accept_ incoming SSL connections from peers. **📌 NOTE**\ To configure this DataSource to _initiate_ an SSL connection to a peer, set the [`ssl`](datasource-datasource-peers-configuration-part-1.md#ssl) option of this DataSource’s [add-peer](datasource-datasource-peers-configuration-part-1.md#add-peer) configuration item for the peer. If you set `datasrc-ssl-enable` to `TRUE`, remember to specify values for the following configuration items: * [datasrc-ssl-port](#datasrc-ssl-port) * For a C-based DataSource application: [datasrc-ssl-certificate](#datasrc-ssl-certificate) and [datasrc-ssl-privatekey](#datasrc-ssl-privatekey) * For a Java-based Datasource application: [datasrc-ssl-keystore](#datasrc-ssl-keystore) and [datasrc-ssl-certificate](#datasrc-ssl-certificate) **Use in:** C, Java **Syntax:** `datasrc-ssl-enable ` **Type:** boolean **Default value:** `FALSE` (incoming SSL connections not accepted) ## datasrc-ssl-certificate `datasrc-ssl-certificate` specifies the path to the certificate that this DataSource application sends to an SSL client. **📌 NOTE**\ For the SSL certificate that an SSL client 'presents' to an SSL server, see the configuration option [ssl-present-certificate](datasource-datasource-peers-configuration-part-1.md#ssl-present-certificate) of the [add-peer](datasource-datasource-peers-configuration-part-1.md#add-peer) option. Use this configuration item in a DataSource application that acts as an SSL server (that is, it accepts incoming SSL connections from peers). * In C-based applications `datasrc-ssl-certificate` is the path to and filename of the certificate file in PEM format. * In Java-based applications, it specifies the alias for a certificate held in the Java KeyStore file specified by [datasrc-ssl-keystore](#datasrc-ssl-keystore). The directory path can contain the following substitution parameters: | Token | Description | | --- | --- | | %r | This DataSource’s [application-root](datasource-run-time-environment-configuration.md#application-root) | | %a | This DataSource’s [application-name](datasource-run-time-environment-configuration.md#application-name) | The DataSource Application won’t start if SSL is enabled (see [datasrc-ssl-enable](#datasrc-ssl-enable)) and `datasrc-ssl-certificate` doesn’t point to a valid certificate. **Use in:** C, Java **Syntax:** **C DataSource applications** ``` datasrc-ssl-certificate ``` **Java DataSource applications** ``` datasrc-ssl-certificate ``` **Type:** string **Default value:** _none_ ### datasrc-ssl-accept-certificate This option is used for for certificate pinning when an SSL connection is being established with a dynamic peer such as one added by Discovery. This option is required if [datasrc-ssl-enable](#datasrc-ssl-enable) is set to `TRUE` and dynamic peers are in use This is functionally equivalent to configuring [ssl-accept-certificate](datasource-datasource-peers-configuration-part-1.md#ssl-accept-certificate) for all dynamically configured peers. **Use in:** C, Java **Since**: DSDK 7.1.30 (Liberator 7.1.30), DataSource for Java 7.1.22 **Syntax:** **C DataSource applications** ``` datasrc-ssl-accept-certificate ``` **Java DataSource applications** ``` datasrc-ssl-accept-certificate ``` **Type:** string **Default value:** __none__ ## datasrc-ssl-cipherlist `datasrc-ssl-cipherlist` configures the SSL/TLS ciphers supported by the DataSource for secure communications with its peers. You should configure this item in conjunction with `datasrc-ssl-options`, and review both regularly as part of your security policy. In C-based DataSource applications, this configuration item takes one value: an OpenSSL cipher list. For a description of the cipher list format, see [Cipher List Format](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT) on the OpenSSL website. In Java-based DataSource applications, the ciphers are provided by the SunJSSE provider (`com.sun.net.ssl.internal.ssl.Provider`) bundled with the JVM. For a detailed list of the available ciphers and enabled ciphers in Java 8, see the documentation for the SunJSSE provider in [Java Cryptography Architecture Oracle Providers Documentation for JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html). To successfully establish an SSL connection, the SSL client and the SSL server must have at least one enabled cipher in common. This item is overridden for a specific peer connection by the [ssl-cipherlist](datasource-datasource-peers-configuration-part-1.md#ssl-cipherlist) option of [add-peer](datasource-datasource-peers-configuration-part-1.md#add-peer). **Use in:** C, Java **Syntax:** * **C**: `datasrc-ssl-cipherlist [:]...` * **Java**: `datasrc-ssl-cipherlist [,]...` **Type:** string **Default value:** * **C:** `DEFAULT:!RC4-SHA:!RC4-MD5:!DES-CBC3-SHA` (from DataSource 7) * **Java:** the default list of enabled cipher suites in the SunJSSE provider. See the documentation for the SunJSSE provider in [Java Cryptography Architecture Oracle Providers Documentation for JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html). ## datasrc-ssl-keystore `datasrc-ssl-keystore` specifies the path to and filename of the Java KeyStore (JKS). The KeyStore contains the SSL certificate that this DataSource presents to connecting peers, copies of certificates used for certificate pinning, and the SSL private key used to decrypt the symmetric session key received from a DataSource peer. The KeyStore must be in Java JKS Format. For more about certificate pinning, see the Wikipedia article at [https://en.wikipedia.org/wiki/Certificate_pinning#Certificate_pinning](https://en.wikipedia.org/wiki/Certificate_pinning#certificate-pinning) The directory path can contain the following substitution parameters: | Token | Description | | --- | --- | | %r | This DataSource’s [application-root](datasource-run-time-environment-configuration.md#application-root) | | %a | This DataSource’s [application-name](datasource-run-time-environment-configuration.md#application-name) | The Java DataSource application will throw an exception if SSL is enabled ([datasrc-ssl-enable](#datasrc-ssl-enable) is TRUE) and you haven’t specified a Java KeyStore. **📌 NOTE**\ The equivalent configuration items in C-based DataSource applications (including Liberator and Transformer) are [datasrc-ssl-certificate](#datasrc-ssl-certificate) and [datasrc-ssl-privatekey](#datasrc-ssl-privatekey). **Use in:** Java **Syntax:** `datasrc-ssl-keystore ` **Type:** string **Default value:** +[none]+ ## datasrc-ssl-passwordfile `datasrc-ssl-passwordfile` specifies the path to and filename of a password file containing a plain text (unencrypted) password used to access private key files, certificate files and KeyStores. In a C-based DataSource application, the password provides access to the password-protected private key file that’s defined by [datasrc-ssl-privatekey](#datasrc-ssl-privatekey). (Also see the [ssl-passwordfile](datasource-datasource-peers-configuration-part-1.md#ssl-passwordfile) option of [add-peer](datasource-datasource-peers-configuration-part-1.md#add-peer).) In a Java-based DataSource application, the password provides access to the Java KeyStore defined by [datasrc-ssl-keystore](#datasrc-ssl-keystore), and hence to the private key/certificate pairs that are held inside the KeyStore. If the Java keystore or private key file is encrypted with a password and `datasrc-ssl-passwordfile` isn’t defined, then the DataSource application exits in error. **⚠️ WARNING**\ We strongly recommend that you password protect your private key files and Java KeyStores. **Use in:** C, Java **Syntax:** `datasrc-ssl-passwordfile ` **Type:** string **Default value:** +[none]+ ## datasrc-ssl-privatekey `datasrc-ssl-privatekey` specifies the path to and filename of the SSL private key that this DataSource application uses to decrypt the symmetric session key received from a DataSource peer. The file must be in PEM format. Use this configuration item in a C-based DataSource application that acts as an SSL server (that is, it accepts incoming SSL connections from peers). The directory path can contain the following substitution parameters: | Token | Description | | --- | --- | | %r | This DataSource’s [application-root](datasource-run-time-environment-configuration.md#application-root) | | %a | This DataSource’s [application-name](datasource-run-time-environment-configuration.md#application-name) | If this DataSource application initiates the Secure Sockets Layer (SSL) connection to a peer, then set the [ssl-privatekey](datasource-datasource-peers-configuration-part-1.md#ssl-privatekey) option of the [add-peer](datasource-datasource-peers-configuration-part-1.md#add-peer) entry for the connection. **📌 NOTE**\ The equivalent configuration in Java DataSource applications is [datasrc-ssl-keystore](#datasrc-ssl-keystore). **Use in:** C **Syntax:** `datasrc-ssl-privatekey ` **Type:** string **Default value:** [none] In a C-based Datasource application, if SSL is enabled ([datasrc-ssl-enable](#datasrc-ssl-enable) is `TRUE`), you must specify a `datasrc-ssl-privatekey`. ## datasrc-ssl-ssloptions `datasrc-ssl-ssloptions` specifies the levels of the SSL protocol that are supported for SSL connections used by this DataSource application. **Use in:** C, Java **Syntax:** `datasrc-ssl-ssloptions ` **Type:** string **Default value:** * **C:** `SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1` (from DataSource 7) * **Java:** `TLS` **Values accepted:** For C-based DataSource applications: | 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 [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 SSLv2. | | `SSL_OP_NO_SSLv3` | Disable support for SSLv3. | | `SSL_OP_NO_TLSv1` | Disable support for TLSv1. | | `SSL_OP_NO_TLSv1_1` | Disable support for TLSv1.1. | | `SSL_OP_NO_TLSv1_2` | Disable support for TLSv1.2. | | `SSL_OP_NO_TLSv1_3` | Disable support for TLSv1.3. | | `SSL_OP_CIPHER_SERVER_PREFERENCE` | In a TLS handshake, the TLS client presents the DataSource with a list of the ciphers it supports in priority order, and the DataSource chooses a cipher from the list. By default, and in accordance with the TLS specification, the DataSource chooses the client’s most preferred cipher from the ciphers they have in common. When `SSL_OP_CIPHER_SERVER_PREFERENCE` is set, the DataSource chooses its most preferred cipher from the ciphers they have in common. This breaks with the TLS specification. The DataSource’s cipher preferences are determined by the order of ciphers in [`datasrc-ssl-cipherlist`](#datasrc-ssl-cipherlist). Ciphers are listed in descending order of preference, most preferred cipher first. Available from DSDK 7.1.25. | You can specify multiple values using the `|` operator. In the example below, support for SSLv2, SSLv3, and TLSv1 has been disabled: ``` datasrc-ssl-options SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1 ``` For Java-based DataSource applications (built under Java Platform Standard Edition 7), see the **Protocols** section of [Java Cryptography Architecture Oracle Providers Documentation for JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html). ## datasrc-ssl-port `datasrc-ssl-port` specifies the network port to listen on for Secure Sockets Layer (SSL) connection requests from DataSource peers. The default of `0` means that no SSL connections can be made to this DataSource application. **Use in:** C, Java **Syntax:** `datasrc-ssl-port ` **Type:** integer **Default value:** `0` (No SSL connections can be made.) ## ssl-config-name `ssl-config-name` specifies the path to and filename of the OpenSSL configuration file that’s loaded by this DataSource application. One use for such a file is to allow the application access to a global trust store. **Use in:** C **Syntax:** `ssl-config-name ` **Type:** string **Default value:** `NULL` (no file provided) ## ssl-debug `ssl-debug` enables SSL debugging output for secure DataSource peer connections. The SSL handshake details are written to stderr and, from Platform 6.2 onwards, as DEBUG level entries in this DataSource application’s event log. `ssl-debug` does not enable debugging output for Liberator’s secure RTTP interfaces: [HTTPS](../liberator/liberator-configure-how-liberator-handles-https-connections.md) and secure [direct](../liberator/liberator-configure-how-liberator-handles-direct-client-connections.md) connections. **Use in:** C **Syntax:** `ssl-debug ` **Type:** boolean **Default value:** `FALSE` ## ssl-engine-flags `ssl-engine-flags` specifies the OpenSSL engine flags that are to be passed to the ENGINE implementation at run time. **Use in:** C **Syntax:** `ssl-engine-flags flag1|flag2|flag3|...` **Type:** string **Default value:** +[ENGINE use is disabled]+ **Values accepted:** | Flag | Description | | --- | --- | | `dh` | Limit engine usage to DH operations only | | `dsa` | Limit engine usage to DSA operations only | | `rand` | Limit engine usage to random operations only | | `rsa` | Limit engine usage to RSA operations only | | `all` | Allow OpenSSL to use any of the above operations | Use the `|` operator to specify multiple flag values. For example, to allow the engine to use both `dsa` and `rsa` operations, specify: ``` ssl-engine-flags dsa|rsa ``` ## ssl-engine-id `ssl-engine-id` specifies the OpenSSL ENGINE cryptographic module to be used. OpenSSL has built-in support for cryptographic acceleration. An application can get a reference to a specific representation, often a hardware device. These representations are referred to as ENGINES. For more about this, see [engine](https://docs.openssl.org/1.1.1/man1/engine) on the OpenSSL website. The default value of `openssl`, or the value `software`, prevent the DataSource application from attempting to use an SSL card. If you set the value `all`, the application attempts to find and use any SSL cards available on the machine. Any other value is considered to represent a specific SSL card - please refer to the OpenSSL documentation for a full list of what’s supported. **Use in:** C **Syntax:** `ssl-engine-id ` **Type:** string **Default value:** `openssl` (The engine uses the normal built-in Open SSL software functions rather than a hardware device.) ## ssl-random-seed `ssl-random-seed` overrides OpenSSL’s automatic seeding of its pseudo random number generator (PRNG) by providing an explicit source of random data with which to seed the PRNG. On Linux, the OpenSSL PRNG is automatically seeded from the non-blocking device file `/dev/urandom`. On Microsoft Windows, the PRNG is automatically seeded from [CryptGenRandom](https://learn.microsoft.com/en-gb/windows/win32/api/wincrypt/nf-wincrypt-cryptgenrandom) and other sources of entropy. Source: [Random Numbers: Seeds](https://wiki.openssl.org/index.php/Random_Numbers#Seeds) on the _OpenSSL Wiki_. If the standard sources of entropy used to automatically seed OpenSSL’s PRNG do not comply with your organisation’s security policy, `ssl-random-seed` provides you with the flexibility to seed OpenSSL’s PRNG with a specific source of entropy. **Use in:** C **Syntax**: `ssl-random-seed [] []` | <source> | Description | | --- | --- | | `builtin` | Seed the PRNG from `/dev/urandom` on Linux or [CryptGenRandom](https://learn.microsoft.com/en-gb/windows/win32/api/wincrypt/nf-wincrypt-cryptgenrandom) and other sources of entropy on Microsoft Windows. Arguments `path` and `bytes` are ignored. | | `file` | Uses the first `` bytes of the data in the file `` to seed the PRNG. If the path to the file is relative, the path is relative to the DataSource application’s root directory. | | `exec` | Uses the first `` bytes of the output from the command specified in `` to seed the PRNG. If the path to the command is relative, the path is relative to the DataSource application’s root directory. | **Type:** string **Default value:** `builtin` **Examples** * `ssl-random-seed builtin` * `ssl-random-seed file /dev/hwrng 1024` --- **See also:** * How can I... [Set up secure connections between DataSource applications](datasource-set-up-secure-connections-between-datasource-applications.md) * Reference: The `ssl` options of [add-peer](datasource-datasource-peers-configuration-part-1.md#add-peer) * [DataSource configuration reference: Introduction](datasource-datasource-configuration-reference-introduction.md)