# 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 the OpenSSL Toolkit. ([https://www.openssl.org/](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, private key and public key (see [datasrc-ssl-keystore](#datasrc-ssl-keystore)). The KeyStore can be accessed using an alias (see [datasrc-ssl-certificate](#datasrc-ssl-certificate)). ## Applicability This version of the DataSource SSL configuration is available in **release 6.2 and later** of the following APIs and Caplin Platform components: * C DataSource API * Caplin Integration Suite * Liberator * Transformer Older versions of these APIs and components use an earlier, incompatible version of the configuration. For details, see section 12.8 "Direct connections using SSL" in the **[Liberator 6.0 Administration Guide](https://docs.caplin.com/developer/docs/Liberator60AdminGuide.pdf)**. ## Configuration items Here’s a list of all the SSL configuration items; to get more detail, just click on the item you’re interested in. **📌 NOTE**\ "_this DataSource application_" means the DataSource application for which you are defining the configuration. "_DataSource peer_" or "_peer_" means a DataSource application that this DataSource application communicates with. * [datasrc-ssl-enable](#datasrc-ssl-enable) * [datasrc-ssl-certificate](#datasrc-ssl-certificate) * [datasrc-ssl-cipherlist](#datasrc-ssl-cipherlist) * [datasrc-ssl-keystore](#datasrc-ssl-keystore) * [datasrc-ssl-passwordfile](#datasrc-ssl-passwordfile) * [datasrc-ssl-privatekey](#datasrc-ssl-privatekey) * [datasrc-ssl-ssloptions](#datasrc-ssl-ssloptions) * [datasrc-sslport](#datasrc-sslport) * [ssl-config-name](#ssl-config-name) * [ssl-debug](#ssl-debug) * [ssl-engine-flags](#ssl-engine-flags) * [ssl-engine-id](#ssl-engine-id) * [ssl-random-seed](#ssl-random-seed) * **[add-peer](datasource-datasource-peers-configuration-part-1.md#add-peer)**'s SSL options on the [DataSource peers configuration (part 1)](datasource-datasource-peers-configuration-part-1.md) page: * [ssl](datasource-datasource-peers-configuration-part-1.md#ssl) * [ssl-accept-certificate](datasource-datasource-peers-configuration-part-1.md#ssl-accept-certificate) * [ssl-cipherlist](datasource-datasource-peers-configuration-part-1.md#ssl-cipherlist) * [ssl-passwordfile](datasource-datasource-peers-configuration-part-1.md#ssl-passwordfile) * [ssl-present-certificate](datasource-datasource-peers-configuration-part-1.md#ssl-present-certificate) * [ssl-privatekey](datasource-datasource-peers-configuration-part-1.md#ssl-privatekey) * [ssl-verify-mode](datasource-datasource-peers-configuration-part-1.md#ssl-verify-mode) ### datasrc-ssl-enable `datasrc-ssl-enable` specifies when `TRUE` that this DataSource application accepts incoming SSL connections from peers. If you set it to `TRUE`, make sure you also specify the following items in the configuration: * [datasrc-ssl-port](#datasrc-sslport) * 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) **📌 NOTE**\ If this DataSource application _initiates_ the Secure Sockets Layer (SSL) connection to a peer, set the [ssl](datasource-datasource-peers-configuration-part-1.md#ssl) option of the [add-peer](datasource-datasource-peers-configuration-part-1.md#add-peer) entry for the connection to `TRUE`, and set the other SSL related options of the `add-peer` as required. ### datasrc-ssl-certificate `datasrc-ssl-certificate` specifies the path to and filename of the certificate that this DataSource application sends to the client when the client requests the server’s (DataSource application’s) certificate for the SSL handshake. This configuration item is required if [datasrc-ssl-enable](#datasrc-ssl-enable) is set to `TRUE`. 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 parameters `%r` and `%a` At run time, `%r` is replaced by the root directory ([application-root](datasource-run-time-environment-configuration.md#application-root)) under which this DataSource application runs, and `%a` is replaced by the DataSource [application-name](datasource-run-time-environment-configuration.md#application-name). **📌 NOTE**\ 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__ **📌 NOTE**\ If this DataSource application _initiates_ the Secure Sockets Layer (SSL) connection to a peer, set the [ssl-present-certificate](datasource-datasource-peers-configuration-part-1.md#ssl-present-certificate) option of the [add-peer](datasource-datasource-peers-configuration-part-1.md) entry for the connection. ### datasrc-ssl-cipherlist `datasrc-ssl-cipherlist` specifes a colon separated list of cipher strings. These cipher strings select, in preferred order, the various SSL ciphers (cryptographic algorithms) that the DataSource application can use for its secure connections. _In C-based DataSource applications_, the ciphers are selected from the set available in the version of [OpenSSL](https://www.openssl.org) built into the DataSource application. 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, the DataSource application 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. _For Java-based DataSource applications_, built under Java Platform Standard Edition 7, there’s information about the available ciphers at [http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html](https://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html) For an SSL connection to be established between two DataSource applications, the application that is the SSL client must have in its `datasrc-ssl-cipherlist` the SSL cipher that the SSL server application wishes to use. 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:** `datasrc-ssl-cipherlist ::...` **Type:** string **Default value:** * C-based applications: DEFAULT (The default list of OpenSSL ciphers. This varies according to the version of OpenSSL built into the DataSource application.) * Java-based applications: The cipher returned by the getDefaultAlgorithm() method of the javax.net.ssl package’s KeyManagerFactory class (see [KeyManagerFactory](https://docs.oracle.com/javase/7/docs/api/javax/net/ssl/KeyManagerFactory.html)). Which particular cipher is returned depends on the version of Java you’ve installed. **Example:** ``` datasrc-ssl-cipherlist HIGH:MEDIUM ``` ### 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 parameters `%r` and `%a` At run time, `%r` is replaced by the root directory ([application-root](datasource-run-time-environment-configuration.md#application-root)) under which this DataSource application runs, and `%a` is replaced by the DataSource [application-name](datasource-run-time-environment-configuration.md#application-name). **Use in:** Java In C-based DataSource applications (including Liberator and Transformer) use [datasrc-ssl-certificate](#datasrc-ssl-certificate) and [datasrc-ssl-privatekey](#datasrc-ssl-privatekey). **Syntax:** `datasrc-ssl-keystore ` **Type:** string **Default value:** +[none]+ **📌 NOTE**\ 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. ### 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) and access to the certificate file that’s paired with this private key. (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. **📌 NOTE**\ We strongly recommend that you password protect your private key files, certificate files and Java KeyStores. **Use in:** C, Java **Syntax:** `datasrc-ssl-passwordfile ` **Type:** string **Default value:** +[none]+ **📌 NOTE**\ If the KeyStore or private key file requires a password to access it and `datasrc-ssl-passwordfile` isn’t defined, the DataSource application exits in error. ### 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 parameters `%r` and `%a` At run time, `%r` is replaced by the root directory ([application-root](datasource-run-time-environment-configuration.md#application-root)) under which this DataSource application runs, and `%a` is replaced by the DataSource [application-name](datasource-run-time-environment-configuration.md#application-name). **Use in:** C In Java-based DataSource applications use[datasrc-ssl-keystore](#datasrc-ssl-keystore). **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`. **📌 NOTE**\ If this DataSource application _initiates_ the Secure Sockets Layer (SSL) connection to a peer, 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. ### 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-based applications: `SSL_OP_NO_SSLv2` * Java-based applications: `TLS` **Values accepted:** _For C-based DataSource applications:_ | Value | Meaning | | --- | --- | | `SSL_OP_ALL` | All SSL protocol levels are supported. | | `SSL_OP_NO_SSLv3` | The SSLv3 protocol is not supported. | | `SSL_OP_NO_SSLv2` | The SSLv2 protocol is not supported. | | `SSL_OP_NO_TLSv1` | The SSLv1 protocol is not supported. | You can specify multiple values using the `|` operator, as in this example: ``` https-ssl-options SSL_OP_NO_TLSV1|SSL_OP_NO_SSLV2 ``` `SSL_OP_NO_TLSV1|SSL_OP_NO_SSLV2` means that all protocol levels are supported except `SSLv1` and `SSLv2` For Java-based DataSource applications (built under Java Platform Standard Edition 7), see the **Protocols** section of [http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html](https://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html) ### datasrc-sslport `datasrc-sslport` 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-sslport ` **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:** `datasrc-ssl-config-name ` **Type:** string **Default value:** `NULL` (no file provided) ### ssl-debug `ssl-debug` enables SSL debugging. 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. **Use in:** C **Syntax:** `datasrc-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. 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` specifies the seeding of the OpenSSL random number generator that’s used for DataSource SSL connections, for Liberator HTTPS connections and secure direct connections from clients, and for generating Liberator session IDs. **Use in:** C **Syntax:** `ssl-random-seed ` Where `` is the type of random number generation required, as follows: | <type> | Description | | --- | --- | | `builtin` | Uses various system commands to produce random output. `` and `` aren’t required. | | `file` | Uses the first `` bytes of the data in the file `` to seed the random number generator. The file is assumed to be located relative to the DataSource application’s root directory. | | `exec` | Uses the first `` bytes of the output from the command specified in `` to seed the random number generator. The command is assumed to be located relative to the DataSource application’s root directory. | **Type:** string **Default value:** On Linux, OpenSSL is seeded by a hardware device so `ssl-random-seed` defaults to this. **Examples** ``` ssl-random-seed builtin ssl-random-seed file etc/randomdata ssl-random-seed file etc/randomdata 1024 ssl-random-seed exec etc/random.sh ssl-random-seed exec etc/random.sh 512 ``` --- **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)