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 shows configuration for an SSL connection between Liberator and a C-based Integration Adapter, and the second example is for Liberator connecting to a Java-based Integration Adapter. 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.
These examples of DataSource SSL configuration apply to release 6.2 and later of the following APIs and Caplin Platform components:
C DataSource API
Caplin Integration Suite
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.
SSL connections for C-based DataSource applications
Assume you have two DataSource applications, one is a Liberator called MyLiberator and the other is a C-based Integration Adapter called MyIntegrationAdapter. 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, though you’d normally add some to a real setup.
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 TRUEtells the Adapter to initiate an SSL connection with its peer (the Liberator).
ssl-present-certificatemust be present. It specifies the SSL certificate file that MyIntegrationAdapter sends to MyLiberator when initiating the secure connection. This is the certificate that identifies MyIntegrationAdapter to MyLiberator.
ssl-privatekeymust be present too. It specifies the SSL private key associated with the certificate specified by
ssl-present-certificate. MyIntegrationAdapter uses the key to decrypt messages from MyLiberator.
ssl-accept-certificatespecifies the SSL certificate file that MyIntegrationAdapter uses for 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-certificatefile. If the keys don’t match, the adapter terminates the (probably unauthorised) connection.
You can supply a chain of certificates for 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-CAwhere
Root-CAis 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
verifycommand (use the
ssl-passwordfilespecifies a file that contains a plain text (unencrypted) password used to access the private key file and the certificate files specified by
And finally, the global item
ssl-config-namespecifies 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.
|The two certificate files and the private key file must be in PEM format.|
|For more about certificate pinning, see the Wikipedia article at https://en.wikipedia.org/wiki/Certificate_pinning#Certificate_pinning.|
|You might also need to seed the Open SSL random number generator.|
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 TRUEtells the Liberator to accept incoming SSL connections from Datasource peers.
datasrc-ssl-portspecifies 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-certificatespecifies 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-privatekeyspecifies 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-passwordfilespecifies a file that contains a plain text (unencrypted) password used to access the private key file and the certificate file specified by
|We strongly recommend that you password protect the private key file and certificate file.|
ssl-config-name(optional) specifies the OpenSSL configuration file that’s loaded by MyLiberator
add-peerconfiguration specifies the SSL connection to MyIntegrationAdapter:
ssl TRUEensures that the Liberator will only accept SSL connection requests from MyIntegrationAdapter; it rejects any request for a non-secure connection.
ssl-accept-certificatespecifies 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-certificatefile. 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 connections for Java-based DataSource applications
What if your Integration Adapter is written in Java? (It will be if you’ve implemented it using the Caplin Integration Suite.) In that case, the SSL configuration is slightly different. Following on from the C-based configuration example above, assume that now you want to replace MyIntegrationAdapter with a Java version called MyJavaAdapter, and as before, MyJavaAdapter connects to MyLiberator through a secure connection using SSL.
The Liberator (SSL server) configuration doesn’t change, other than the Adapter name in the
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/MyIntegrationAdapterCert.pem end-peer
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 <MyLiberators-hostname> port <MyLiberators-portnumber> ssl TRUE ssl-present-certificate <certificate-name-in-datasrc-ssl-keystore> ssl-accept-certificate <certificate-name-in-datasrc-ssl-keystore> end-peer ssl-config-name /etc/pki/tls/openssl.cnf
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
If you want to password protect the KeyStore, specify the password file in
|We strongly recommend that you password protect the Java KeyStore.|
ssl-present-certificatemust be present. It specifies the SSL certificate file 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-certificateis just the name of the relevant certificate in the KeyStore.
ssl-accept-certificatespecifies the name of an SSL certificate file in the 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.
You can supply a chain of certificates for certificate pinning, as long as they’re in PKCS#7 format. You import the chain to the Java KeyStore using the KeyStore 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-CAwhere
Root-CAis the highest level CA. Then set
ssl-accept-certificateto the name of the lowest level certificate in the chain; in the example here, this would be to
And finally, the (optional) item
ssl-config-namespecifies the OpenSSL configuration file that’s loaded by MyJavaAdapter.
C-based DataSource applications use the OpenSSL 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:
Setting strong encryption (encryption key length)
To ensure adequate security In a production deployment, the encryption keys you use (as defined in the certificates) must be at least 128 bits long.
Additionally, make sure that the list of SSL ciphers (cryptographic algorithms) available to your DataSource application includes ciphers that support keys of 128 bits or more. In C-based DataSource applications, the ciphers are selected from the set available in the version of OpenSSL built into the application, and In Java-based DataSource applications they’re selected from the set provided with Java (see the Java Cryptography Architecture Oracle Providers Documentation for the version of Java used by your application). You specify the set of ciphers to use through the DataSource configuration item
For C-based DataSource applications, we recommend you define
datasrc-ssl-cipherlist as follows:
This configuration setting ensures that Windows-based C DataSource applications can use encryption keys of least 128 bits. Linux-based C DataSource applications can use just the value
HIGH+TLSV1 amounts to the same thing on LInux, so you can use the above configuration in both Windows and Linux environments.
In C-based Datasource applications running under Windows, the configuration setting
|For more information about the SSL cipher list for Open SSL, see the OpenSSL ciphers(1) manual page, which includes a list of the available cipher suite names.|