DataSource Secure Sockets Layer (SSL) configuration

Set datasrc-ssl-enable to TRUE to enable this DataSource to accept incoming SSL connections from peers.

If you set datasrc-ssl-enable to TRUE, remember to specify values for the following configuration items:

Use in: C, Java

Syntax: datasrc-ssl-enable <boolean>

Type: boolean

Default value: FALSE (incoming SSL connections not accepted)

datasrc-ssl-certificate specifies the path to the certificate that this DataSource application sends to an SSL client.

Use this configuration item in a 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:

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:

Type: string

Default value: none

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

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:

Type: string

Default value:

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 following substitution parameters:

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.

Use in: Java

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

Type: string

Default value: [none]

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

Use in: C, Java

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

Type: string

Default value: [none]

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:

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.

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

Values accepted:

For C-based DataSource applications:

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

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

Type: string

Default value: NULL (no file provided)

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 and secure direct connections.

Use in: C

Syntax: ssl-debug <boolean>

Type: boolean

Default value: FALSE

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:

Use the | operator to specify multiple flag values. For example, to allow the engine to use both dsa and rsa operations, specify:

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 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 <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 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 and other sources of entropy. Source: 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> [<path>] [<bytes>]

Type: string

Default value: builtin

Examples

See also: