# Set up secure connections between DataSource applications Here are some examples that show you how to configure secure connections between two DataSource applications using the Secure Sockets Layer (SSL) The [first example](#ssl-connection-between-two-c-datasource-applications) shows configuration for an SSL connection between [Liberator](../liberator/index.md) and a C-based [Integration Adapter](../platform-architecture/putting-data-into-the-platform.md), and the [second example](#ssl-connection-between-a-java-datasource-and-a-c-datasource) is for Liberator connecting to a Java-based Integration Adapter. These examples of DataSource SSL configuration apply to release 6.2 and later of the following APIs and Caplin Platform components. 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" of the [Liberator 6.0 Administration Guide](https://docs.caplin.com/developer/docs/Liberator60AdminGuide.pdf). The examples assume you know how to obtain an SSL certificate, private key and public key, and, for the Java-based Integration Adapter, that you know how to set up a Java Keystore. ## SSL connection between two C DataSource applications Assume you have two DataSource applications: a C-based integration adapter, called **MyIntegrationAdapter**, and a Liberator, called **MyLiberator**. The following configurations allow MyIntegrationAdapter to connect to MyLiberator through a secure connection using SSL. For the sake of clarity, the Liberator configuration doesn’t include any [data services](datasource-data-services.md), which you would normally include in a real setup. ### C-based adapter’s configuration Peer SSL connnection configuration for MyIntegrationAdapter (the Adapter is the SSL client): ``` datasrc-name MyIntegrationAdapter-%h datasrc-local-label MyIntegrationAdapter add-peer remote-name MyLiberator remote-label MyLiberator addr port ssl TRUE ssl-present-certificate %r/certs/MyIntegrationAdapterCert.pem ssl-accept-certificate %r/certs/rttpd.pem ssl-privatekey %r/certs/MyIntegrationAdapterPkey.key ssl-passwordfile %r/certs/MyIntegrationAdapterPassword.pwd end-peer ssl-config-name /etc/pki/tls/openssl.cnf ``` Here’s an explanation of what the ssl options in MyIntegrationAdapter’s add-peer are for: * `[ssl](datasource-datasource-peers-configuration-part-1.md#ssl) TRUE` tells the Adapter to initiate an SSL connection with its peer (the Liberator). * [`ssl-present-certificate`](datasource-datasource-peers-configuration-part-1.md#ssl-present-certificate) specifies the SSL certificate file in PEM format that MyIntegrationAdapter sends to MyLiberator when initiating the secure connection. This is the certificate that identifies MyIntegrationAdapter to MyLiberator. * [`ssl-privatekey`](datasource-datasource-peers-configuration-part-1.md#ssl-privatekey) specifies the SSL private key file in PEM format associated with the certificate specified by `ssl-present-certificate`. MyIntegrationAdapter uses the key to decrypt messages from MyLiberator. * [`ssl-accept-certificate`](datasource-datasource-peers-configuration-part-1.md#ssl-accept-certificate) specifies the SSL certificate file in PEM format that MyIntegrationAdapter uses for [certificate pinning](https://en.wikipedia.org/wiki/Certificate_pinning#certificate-pinning). When the SSL connection is being established with MyLiberator, MyIntegrationAdapter compares the public key in the certificate received from the Liberator against the public key in the `ssl-accept-certificate` file. If the keys don’t match, the adapter terminates the (probably unauthorised) connection. You can supply a chain of certificates for [certificate pinning](https://en.wikipedia.org/wiki/Certificate_pinning#certificate-pinning), as long as they’re concatenated together into a single SSL certificate file that’s supplied to `ssl-accept-certificate`. The certificates must be added to the file such that the highest level CA is last in the chain; for example: `MyCertificate -> Intermediate-CA-1 -> Intermediate-CA-2 -> Root-CA` where `Root-CA` is the highest level CA. Once you’ve produced the certificate file, you should verify that the chain of certificates it contains is correct. You can do this with the OpenSSL [`verify`](https://docs.openssl.org/1.1.1/man1/verify) command (use the `-CAfile` option). * [`ssl-passwordfile`](datasource-datasource-peers-configuration-part-1.md#ssl-passwordfile) specifies a file that contains a plain text (unencrypted) password used to access the private key file and the certificate files specified by `ssl-privatekey` and `ssl-passwordfile`. * [`ssl-config-name`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#ssl-config-name) specifies the OpenSSL configuration file that’s loaded by MyIntegrationAdapter. You don’t have to supply a configuration file for OpenSSL, but if you don’t, OpenSSL will use its default settings. ### Liberator’s SSL configuration Peer SSL connection configuration for MyLiberator (Liberator is the SSL server): ``` datasrc-name MyLiberator-%h datasrc-local-label MyLiberator datasrc-ssl-enable TRUE datasrc-ssl-port 25001 datasrc-ssl-certificate %r/certs/rttpd.pem datasrc-ssl-privatekey %r/certs/rttpd.key datasrc-ssl-passwordfile %r/certs/rttpd.pwd ssl-config-name /etc/pki/tls/openssl.cnf add-peer remote-name MyIntegrationAdapter remote-label MyIntegrationAdapter ssl TRUE ssl-accept-certificate %r/certs/MyIntegrationAdapterCert.pem end-peer ``` Here’s an explanation of what MyLiberator’s ssl configuration items do: * `[datasrc-ssl-enable](datasource-datasource-secure-sockets-layer-ssl-configuration.md#datasrc-ssl-enable) TRUE` tells the Liberator to accept incoming SSL connections from Datasource peers. * [`datasrc-ssl-port`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#datasrc-ssl-port) specifies the network port that the Liberator is to listen on for Secure Sockets Layer (SSL) connection requests from DataSource peers. You must specify a port, otherwise the Liberator won’t accept incoming SSL connections, regardless of whether datasrc-ssl-enable is set to TRUE. * [`datasrc-ssl-certificate`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#datasrc-ssl-certificate) specifies the certificate that the Liberator sends to an SSL client (in this case, MyIntegrationAdapter) when the client requests the server’s (Liberator’s) certificate for the SSL handshake. * [`datasrc-ssl-privatekey`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#datasrc-ssl-privatekey) specifies the SSL private key that the Liberator uses to decrypt the symmetric session key received from a DataSource peer (in this case, from MyIntegrationAdapter). * [`datasrc-ssl-passwordfile`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#datasrc-ssl-passwordfile) specifies a file that contains a plain text (unencrypted) password used to access the private key file and the certificate file specified by `datasrc-ssl-privatekey` and `datasrc-ssl-passwordfile`. **⚠️ WARNING**\ We strongly recommend that you password protect the private key file and the certificate file. * [`ssl-config-name`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#ssl-config-name) (optional) specifies the OpenSSL configuration file that’s loaded by MyLiberator * The [`add-peer`](datasource-datasource-peers-configuration-part-1.md#add-peer) configuration specifies the SSL connection to MyIntegrationAdapter: * `[remote-label](datasource-datasource-peers-configuration-part-1.md#remote-label) MyIntegrationAdapter` matches the [datasrc-local-label](datasource-datasource-peers-configuration-part-2.md#datasrc-local-label) in MyIntegrationAdapter’s configuration. * `[ssl](datasource-datasource-peers-configuration-part-1.md#ssl) TRUE` ensures that the Liberator will only accept SSL connection requests from MyIntegrationAdapter; it rejects any request for a non-secure connection. * [`ssl-accept-certificate`](datasource-datasource-peers-configuration-part-1.md#ssl-accept-certificate) specifies the SSL certificate file that the Liberator uses for certificate pinning. When the SSL connection is being established with MyIntegrationAdapter, Liberator compares the public key in the certificate received from the MyIntegrationAdapter against the public key in the `ssl-accept-certificate` file. If the keys don’t match, the Liberator terminates the (probably unauthorised) connection. The certificate file and the private key file must be in PEM format. ## SSL connection between a Java DataSource and a C Datasource The SSL configuration is slightly different for Java adapters. Following on from the [C-based configuration example above](#ssl-connection-between-two-c-datasource-applications), assume that now you want to replace **MyIntegrationAdapter** with a Java version called **MyJavaAdapter**. ### Java-based adapter’s SSL configuration The configuration for MyJavaAdapter (the SSL client) looks like this: ``` datasrc-name MyJavaAdapter-%h datasrc-local-label MyJavaAdapter datasrc-ssl-keystore %r/certs/MyJavaAdapterKeyStore.jks datasrc-ssl-passwordfile %r/certs/MyJavaAdapterPassword.pwd add-peer remote-name MyLiberator remote-label MyLiberator addr port ssl TRUE ssl-present-certificate ssl-accept-certificate end-peer ssl-config-name /etc/pki/tls/openssl.cnf ``` Here’s an explanation of the configuration above: * Rather than putting MyJavaAdapter’s SSL certificate and private key in separate files, you keep them in a Java KeyStore, along with copies of the certificates used for certificate pinning. You specify the KeyStore in [`datasrc-ssl-keystore`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#datasrc-ssl-keystore). * If you want to password protect the KeyStore, specify the password file in [`datasrc-ssl-passwordfile`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#datasrc-ssl-passwordfile). **⚠️ WARNING**\ We strongly recommend that you password protect the Java Keystore. * As in the C-based Adapter example, the `[ssl](datasource-datasource-peers-configuration-part-1.md#ssl) TRUE` option of the [`add-peer`](datasource-datasource-peers-configuration-part-1.md#add-peer) tells MyJavaAdapter to initiate an SSL connection with its peer (the Liberator). * [`ssl-present-certificate`](datasource-datasource-peers-configuration-part-1.md#ssl-present-certificate) must be present. It specifies the SSL certificate that MyJavaAdapter sends to MyLiberator when initiating the secure connection. This is the certificate that identifies MyJavaAdapter to MyLiberator. Since we’re keeping the certificate in a Java KeyStore, `ssl-present-certificate` is just the alias of the relevant certificate in the KeyStore. * [`ssl-accept-certificate`](datasource-datasource-peers-configuration-part-1.md#ssl-accept-certificate) specifies the alias of MyLiberator’s public certificate, imported into the adapter’s Java KeyStore. This is the certificate that MyJavaAdapter uses for certificate pinning. When the SSL connection is being established with MyLiberator, MyJavaAdapter compares the public key in the certificate received from the Liberator against the public key for the certificate in the Java KeyStore. If the keys don’t match, the adapter terminates the (probably unauthorised) connection. To import MyLiberator’s certificate into MyJavaAdapter’s keystore, execute the command below: ``` keytool -import -alias myliberator -file rttpd.pem -keystore MyJavaAdapterKeyStore.jks ``` You can supply a _chain_ of certificates for certificate pinning, as long as they’re in [PKCS](https://en.wikipedia.org/wiki/PKCS)#7 format. You import the chain to the Java KeyStore using the [`keytool`](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) utility and the chain is then handled by the standard Java cryptography library. The certificates must be chained such that the highest level CA is last in the chain; for example: `MyCertificate -> Intermediate-CA-1 -> Intermediate-CA-2 -> Root-CA` where `Root-CA` is the highest level CA. Then set `ssl-accept-certificate` to the name of the lowest level certificate in the chain; in the example here, this would be to `MyCertificate`. * And finally, the (optional) item [`ssl-config-name`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#ssl-config-name) specifies the OpenSSL configuration file that’s loaded by MyJavaAdapter. ### Liberator’s SSL configuration The Liberator (SSL server) configuration is very similar to the configuration in the previous example. Note the different adapter name and the different certificate file name in the `add-peer` block: ``` datasrc-name MyLiberator-%h datasrc-local-label MyLiberator datasrc-ssl-enable TRUE datasrc-ssl-port 25001 datasource-ssl-certificate %r/certs/rttpd.pem datasrc-ssl-privatekey %r/certs/rttpd.key datasrc-ssl-passwordfile %r/certs/rttpd.pwd ssl-config-name /etc/pki/tls/openssl.cnf add-peer remote-name MyJavaAdapter remote-label MyJavaAdapter ssl TRUE ssl-accept-certificate %r/certs/MyJavaAdapterCert.pem end-peer ``` The file `MyJavaAdapterCert.pem` is derived from the Java adapter’s certificate stored in the adapter’s keystore, `MyJavaAdapter.jks`. To export the certificate from the keystore, follow the steps below: 1. Enter the command below to export a key pair in [PKCS#12](https://en.wikipedia.org/wiki/PKCS_12) format from the keystore file `MyJavaAdapter.jks`, changing `` to the alias of MyJavaAdapter’s key and certificate and `` to the password with which to encrypt the PKCS#12 file. ``` keytool -importkeystore -srckeystore MyJavaAdapterKeyStore.jks \ -destkeystore MyJavaAdapter.p12 -deststoretype PKCS12 \ -srcalias -deststorepass \ -destkeypass ``` 2. Enter the command below to convert the file `MyJavaAdapter.p12` to a PEM-encoded PKCS#8 file: ``` openssl pkcs12 -in MyJavaAdapter.p12 -out MyJavaAdapter.pem ``` The private key in the PKCS#8 file is encrypted with the same password as it is in the PKCS#12 file. 3. Open the file `MyJavaAdapter.pem`, which contains both the key and certificate (or certificate chain), and copy the certificate (or certificate chain) into a new file, `MyJavaAdapterCert.pem`: ``` -----BEGIN CERTIFICATE----- MIIDhTCCAm2gAwIBAgIEQWyp/TANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJH ⋮ As7CYxDrCuleFcJxD2TaeqgtfMKs1TwZSpgnF79RpVZm2lN/D8KrMlA= -----END CERTIFICATE----- ``` ## Configuring OpenSSL C-based DataSource applications use the [OpenSSL](https://www.openssl.org) software to implement the security policies for secure connections with peers. You can configure OpenSSL using the following DataSource configuration items, which are defined on the page [DataSource Secure Sockets Layer (SSL) configuration](datasource-datasource-secure-sockets-layer-ssl-configuration.md): * [`ssl-config-name`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#ssl-config-name) * [`ssl-debug`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#ssl-debug) * [`ssl-engine-flags`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#ssl-engine-flags) * [`ssl-engine-id`](datasource-datasource-secure-sockets-layer-ssl-configuration.md#ssl-engine-id) When you change the configuration of OpenSSL within Liberator, the new settings also apply to all of Liberator’s [HTTPS connections](../liberator/liberator-configure-how-liberator-handles-https-connections.md) and [Direct secure connections](../liberator/liberator-configure-how-liberator-handles-direct-client-connections.md), as well as to secure connections between with its peers. ## Specifying a list of permitted ciphers To ensure adequate security in a production deployment, regularly review the list of ciphers permitted for use in SSL communications. Useful sources of security resources include [Qualys SSL Labs](https://www.ssllabs.com/ssltest/) and [Security/Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) in the Mozilla wiki. To set the list of permitted ciphers, see the documentation for the [datasrc-ssl-cipherlist](datasource-datasource-secure-sockets-layer-ssl-configuration.md#datasrc-ssl-cipherlist) configuration item. --- **See also:** * Reference: [DataSource Secure Sockets Layer (SSL) configuration](datasource-datasource-secure-sockets-layer-ssl-configuration.md) * Reference: [DataSource peers configuration](datasource-datasource-peers-configuration-part-1.md) * [DataSource configuration reference: Introduction](datasource-datasource-configuration-reference-introduction.md) * How can I... [Configure how Liberator handles HTTPS connections](../liberator/liberator-configure-how-liberator-handles-https-connections.md) * How can I... [Configure how Liberator handles direct client connections](../liberator/liberator-configure-how-liberator-handles-direct-client-connections.md)