Author:
Refinitiv Real-Time SDKs support several connection types such as a TCP socket, reliable multicast, HTTP, encryption, and WebSocket when connecting to Advanced Distribution Server (ADS). The initial versions of ADS don’t support encrypted connections so they require an additional encryption device called an SSL accelerator to handle the encryption. The encryption device could be a hardware device or application. For more information, please refer to the Quick steps to set up encrypted connections for ADS with stunnel article.
However, since version 3.4.0.L1, ADS has supported encrypted connections. There is no need to have an SSL accelerator to handle the encryption.
This article demonstrates how to configure ADS to support encrypted connections.
Configuration Steps
There are three steps to configure ADS to support encrypted connections.
1. Generate the server certificate and the server's private key files
The server certificate and server’s private key files are required to configure ADS to support encrypted connections. You may need to contact your IT team to generate those files for you.
Otherwise, you can use the openssl command to generate those files. This is for development/testing purposes only. For the production environment, please contact your Market Data and IT Network teams to set up the certificate and key files.
Run the following command to generate the server certificate and server’s private key files for the www.test.com domain.
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -subj '/CN=www.test.com'
The key.pem file is the server’s private key file and the cert.pem file is the server certificate file.
Then, run the following command to remove the PEM pass phrase from the key.pem file.
cp key.pem key.pem.org
openssl rsa -in key.pem.org -out key.pem
2. Modify the ADS configurations
The following configurations can be used to configure ADS to support encrypted connections.
| Configuration | Description |
|---|---|
| connectionType | This parameter specifies the connection type for this rssl server. There are currently two supported RSSL connection types: · 0: Standard TCP socket · 1: Encrypted connection The default value is 0 (Standard TCP socket). |
| serverCert | This parameter specifies the path and file name of the server certificate for this encrypted RSSL server. |
| serverPrivateKey | This parameter specifies the path and file name of the server certificate for this encrypted RSSL server. |
| cipherSuite | This parameter specifies an optional OpenSSL-formatted cipher suite string for this encrypted RSSL server. |
| dhParams | This parameter specifies an optional Diffie-Hellman parameter file for this encrypted RSSL server. |
Add the following configurations to the ADS configuration file (rmds.cnf, distribution.cnf, or ads_pop.cnf).
*ads*connectionType : 1
*ads*serverCert : /<path>/cert.pem
*ads*serverPrivateKey : /<path>/key.pem
Change <path> to the directory that contain the cert.pem and key.pem files.
3 Run the ADS
Finally, restart or run the ADS. We may need to verify the ADS log file to make sure that the ADS starts properly.
Test the encrypted connections
We can use the EMA examples in the Refinitiv Real-Time SDKs to test the encrypted connections. To test the connection, the cert.pem file is required, so copy the cert.pem from the ADS server to the client machines.
The following sections demonstrate how to configure the examples in the Refinitiv Real-Time SDKs to create encrypted connections to ADS.
If the hostname (www.test.com) can’t be resolved by the DNS, we need to add it and its IP address to the operating system’s host file. For example:
127.0.0.1 www.test.com
Enterprise Message API C++
We can configure EMA C++ to connect to the encrypted server by using the following configurations.
<Channel>
<Name value="Channel_1"/>
<ChannelType value="ChannelType::RSSL_ENCRYPTED"/>
<OpenSSLCAStore value="cert.pem"/>
<EncryptedProtocolType value="EncryptedProtocolType::RSSL_SOCKET"/>
…
<Host value="www.test.com"/>
<Port value="14002"/>
</Channel>
With these configurations, EMA C++ creates an encrypted socket connection to the TCP 14002 port of ADS running on the www.test.com machine. It uses the certificate from the cert.pem file.
Enterprise Transport API C
We can run the VAConsumer example in the ETA package with the following parameters to create an encrypted connection to ADS.
VAConsumer -encryptedSocket www.test.com:14002 ELEKTRON_DD mp:JPY= -castore cert.pem
With the above parameters, the VAConsumer example creates an encrypted socket connection to the TCP 14002 port of ADS running on the www.test.com machine. It uses the certificate from the cert.pem file and subscribes to JPY= from the ELEKTRON_DD service.
Enterprise Message API Java
First, we need to import the certificate file (cert.pem) to the Java truststore file (cacerts). The cacerts file is in the <Java Path>\lib\security\ directory. Run the following command to import the cert.pem to the cacerts file.
keytool.exe -import -alias www.test.com -keystore cacerts -file cert.pem
The default password of the cacerts file is changeit.
Note: It requires the administrator or root privilege to import the certificate to the Java truststore file (cacerts). However, if you would like to build a new key store file, please refer to the Building a keystore file to be used with an HTTPS (or ENCRYPTED) connection type for real-time Java-based APIs article.
Then, configure EMA Java to connect to the encrypted ADS by using the following configurations.
<Channel>
<Name value="Channel_1"/>
<ChannelType value="ChannelType::RSSL_ENCRYPTED"/>
<EncryptedProtocolType value="EncryptedProtocolType::RSSL_SOCKET"/>
…
<Host value="www.test.com"/>
<Port value="14002"/>
</Channel>
With these configurations, EMA Java creates an encrypted socket connection to the TCP 14002 port of ADS running on the www.test.com machine. It uses the certificate from the Java truststore.
Enterprise Transport API Java
First, we need to import the certificate file (cert.pem) to the Java truststore file (cacerts). The cacerts file is in the <Java Path>\lib\security\ directory. Run the following command to import the cert.pem to the cacerts file.
keytool.exe -import -alias www.test.com -keystore cacerts -file cert.pem
The default password of the cacerts file is changeit.
Note: It requires the administrator or root privilege to import the certificate to the Java truststore file (cacerts). However, if you would like to build a new key store file, please refer to the Building a keystore file to be used with an HTTPS (or ENCRYPTED) connection type for real-time Java-based APIs article.
Then, run the com.refinitiv.eta.valueadd.examples.consumer.Consumer example with the following parameters.
-c www.test.com:14002 ELEKTRON_DD mp:JPY= -connectionType encrypted -encryptedConnectionType socket
With the above parameters, the consumer example creates an encrypted socket connection to the TCP 14002 port of ADS running on the www.test.com machine. It uses the certificate from the Java truststore and subscribes to JPY= from the ELEKTRON_DD service.
Troubleshooting
The followings are the list of problems and solutions that you may encounter while configuring the ADS or running the examples.
1. ADS asks for the PEM para phase when it starts
Please make sure that you have removed the PEM pass phrase from the private key file (key.pem) by running the following commands.
cp key.pem key.pem.org
openssl rsa -in key.pem.org -out key.pem
2. The example is unable to connect to the server
The EMA C++ or ETA C examples show the following error messages.
Error: 2000 error on SSL_connect SSL Error: 0 errno: 0
Error: 2002 ripcSSLInit error on SSL_connect SSL. Please verify that the server can accept TLS encrypted connections. Error: 0 errno: 0
The EMA Java or ETA Java examples show the following error messages.
Error initializing channel: errorId=-1 text=Tunnel Channel disconnected
You need to verify the ADS log for the error messages.
<7e8b4376ee6e.1.ads: Error: Thu Sep 02 10:03:38 2021>
RIPC Server "distribution_rssl_sink" initialization failed: </local/jenkins/workspace/RTDS35XCore_Release/OS/OL7-64/esdk/source/rtsdk/Cpp-C/Eta/Impl/Transport/ripcsslutils.c:1507> Error: 2001 ripcSSLSetupCTXServer() error loading certificate from file cert.pemOpenSSL Error string: error:02001002:system library:fopen:No such file or directory:fopen('cert.pem','r'):bss_file.c:402:
OpenSSL Error string: error:20074002:BIO routines:FILE_CTRL:system lib:bss_file.c:404:
OpenSSL Error string: error:140DC002:SSL routines:SSL_CTX_use_certificate_chain_file:system lib:ssl_rsa.c:701:
<END>
The above error indicates that it is unable to load the cert.pem file from the configured directory. We need to verify the location of the cert.pem file and then modify the ADS configurations.
3. The example can connect to the server but it shows the “Hostname mismatch” error
The error messages could be:
Error: 2002 Certificate validation error. OpenSSL Return code: Hostname mismatch
Error initializing channel: errorId=-1 text=No subject alternative names present
Error initializing channel: errorId=-1 text=No name matching <hostname> found
These errors indicate that the hostname used in the examples doesn’t match the common name (CN) in the certificate. To solve these problems, verify the common name (CN) in the certificate and then use it in the examples.
4. Error: 0012 Unable to load openSSL Libraries
On Windows, the libssl (libssl-1_1-x64.dll) and libcryto (libcrypto-1_1-x64.dll) libraries are required to create an encrypted socket connection. You can download these libraries from the OpenSSL website.
5. unable to find valid certification path to requested target
The EMA Java or ETA Java examples show the following error.
Error initializing channel: errorId=-1 text=PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
This error indicates that the JVM is unable to find a valid certificate for the encrypted connection. We can use the following JVM option to verify the problem.
-Djavax.net.debug=all
The output will show the trustStore file used by the application.
javax.net.ssl|DEBUG|01|main|2021-09-02 22:23:26.128 ICT|TrustStoreManager.java:112|trustStore is: C:\Program Files\Java\jdk-11.0.11\lib\security\cacerts
Then, we can use the keytool command to list entries in a keystore.
keytool -list -keystore cacerts -v
If the ADS certificate is not in the list, the keytool command can be used to import it to the trust store.
keytool.exe -import -alias www.test.com -keystore cacerts -file cert.pem
However, if you would like to build a new key store file, please refer to the Building a keystore file to be used with an HTTPS (or ENCRYPTED) connection type for real-time Java-based APIs article.
Summary
ADS version 3.4.0 onwards supports encrypted connections. There are three steps to configure ADS to support encrypted connections. First, generate the server certificate and the server's private key files for the ADS server. Then, specify the connectType, serverCert, and serverPrivateKey configurations in the ADS configuration file. Finally, restart the ADS instance. For the Refinitiv Real-Time SDKs C/C++ applications, the generated certificate file (cert.pem) can be used to connect to the encrypted ADS. However, for the Refinitiv Real-Time SDKs Java application, the certificate file must be imported to the Java trust store or keystore file before connecting to the encrypted ADS.
References
1. 2021. ADVANCED DISTRIBUTION SERVER SOFTWARE INSTALLATION MANUAL. [ebook] Refinitiv, pp.128-129. Available at: <https://my.refinitiv.com/content/dam/myrefinitiv/products/9601/en/Technical/628187.pdf> [Accessed 3 September 2021].
2. Akadia.com. n.d. How to create a self-signed Certificate. [online] Available at: <https://www.akadia.com/services/ssh_test_certificate.html> [Accessed 3 September 2021].
3. Docs.oracle.com. n.d. keytool. [online] Available at: <https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html> [Accessed 3 September 2021].
4. Kunvutipongsak, N., 2021. Building a keystore file to be used with an HTTPS (or ENCRYPTED) connection type for real-time Java-based APIs | Refinitiv Developers. [online] Developers.refinitiv.com. Available at: <https://developers.refinitiv.com/en/article-catalog/article/building-keystore-file-be-used-https-or-encrypted-connection-type-real-time-java-based-apis> [Accessed 3 September 2021].
5. Phuriphanvichai, J., 2018. Quick steps to set up an encrypted connection for ADS with stunnel | Refinitiv Developers. [online] Developers.refinitiv.com. Available at: <https://developers.refinitiv.com/en/article-catalog/article/quick-steps-set-encrypted-connection-ads> [Accessed 3 September 2021].
6. Woitasen, D., 2012. How to generate a self-signed SSL certificate using OpenSSL?. [online] Stack Overflow. Available at: <https://stackoverflow.com/questions/10175812/how-to-generate-a-self-signed-ssl-certificate-using-openssl> [Accessed 3 September 2021].
