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/), and the security certificate and private key are kept in separate PEM files (see datasrc-ssl-certificate and 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). The KeyStore can be accessed using an alias (see 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.

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 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:

If this DataSource application initiates the Secure Sockets Layer (SSL) connection to a peer, set the ssl option of the add-peer entry for the connection to TRUE, and set the other SSL related options of the add-peer as required.

Use in: C, Java

Syntax: datasrc-ssl-enable <boolean>

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 certiticate that an SSL client 'presents' to an SSL server, see the configuration option ssl-present-certificate of the 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.

The directory path can contain the parameters %r and %a  At run time, %r is replaced by the root directory (application-root) under which this DataSource application runs, and %a is replaced by the DataSource application-name.

The DataSource Application won’t start if SSL is enabled (see datasrc-ssl-enable) and datasrc-ssl-certificate doesn't point to a valid certificate.

Use in: C, Java

Syntax:

  • C: datasrc-ssl-certificate <path-to-ssl-certificate-pem-file>
  • Java: datasrc-ssl-certificate <ssl-certificate-alias-in-java-keystore>

Type: string

Default value: [none - but not required unless datasrce-ssl-enable is set to TRUE]

datasrc-ssl-cipherlist

datasrc-ssl-cipherlist specifes the list of ciphers the DataSource is permitted to use for SSL communications.

In C-based DataSource applications, the ciphers are selected from the ciphers included in the version of OpenSSL 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 ciphers(1) manual page. At run time, the DataSource application passes the cipher list as a control string to the OpenSSL function SSL_CTX_set_cipher_list(); this function uses the control string to set up the list of available SSL ciphers.

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 Oracle Java 8, see the documentation for the SunJSSE provider in Java Cryptography Architecture Oracle Providers Documentation for JDK 8.

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 option of add-peer.

Use in: C, Java

Syntax:

  • C: datasrc-ssl-cipherlist <cipher>:<cipher>:<cipher>:...
  • Javadatasrc-ssl-cipherlist <cipher>,<cipher>,<cipher>,...

Type: string

Default value:

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 

The directory path can contain the parameters %r and %a  At run time, %r is replaced by the root directory (application-root) under which this DataSource application runs, and %a is replaced by the DataSource application-name.

The Java DataSource application will throw an exception if SSL is enabled (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 and datasrc-ssl-privatekey.

Use in: Java

Syntax: datasrc-ssl-keystore <keystore-file-path-and-name>

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  and access to the certificate file that's paired with this private key. (Also see the ssl-passwordfile option of add-peer.)

In a Java-based DataSource application, the password provides access to the Java KeyStore defined by 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, certificate files and Java KeyStores.

Use in: C, Java

Syntax: datasrc-ssl-passwordfile <path-to-password-file>

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 parameters %r and %a  At run time, %r is replaced by the root directory (application-root) under which this DataSource application runs, and %a is replaced by the DataSource application-name.

If this DataSource application initiates the Secure Sockets Layer (SSL) connection to a peer, then set the ssl-privatekey option of the add-peer entry for the connection.

Note: the equivalent configuration in Java DataSource applications is datasrc-ssl-keystore.

Use in: C

Syntax: datasrc-ssl-privatekey <PEM-file-path-and-name>

Type: string

Default value: [none] In a C-based Datasource application, if SSL is enabled (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 <supported-SSL-levels>

Type: string

Default value:

  • C: SSL_OP_NO_SSLv2
  • 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 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.

You can specify multiple values using the | operator. In the example below, support for SSLv2, SSLv3, and TLSv1 has been disabled:

https-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.

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 <SSL-port-number>

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 <openssl-config-file-path-and-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 <boolean>

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 https://www.openssl.org/docs/man1.0.2/crypto/engine.html

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 <ENGINE-module-name>

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.

By default, OpenSSL seeds the random number generator using a system-specific entropy source, which is /dev/urandom on UNIX-like operating systems, and is a combination of CryptGenRandom and other sources of entropy on Windows.

Use in: C

Syntax: ssl-random-seed <type> <arg1> <arg2>

Where <type> is the type of random number generation required, as follows:

<type> Description
builtin Uses various system commands to produce random
output. <arg1> and <arg2> aren't required.
file Uses the first <arg2> bytes of the data in the file <arg1> 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 <arg2> bytes of the output from the command specified in <arg1> 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: