Building a keystore file to be used with an HTTPS (or ENCRYPTED) connection type for Java-based Elektron real-time APIs
Elektron real-time APIs (i.e. EMA and ETA) supports various transport types. One of the most familiar connection types is ‘Socket Transport (RSSL)’ that implemented the idea of TCP/IP-based (RFC 971) reliable network protocol which is a packet-switch network. For two hosts to communicate (source and destination), they must packetize their data and submit it to communication devices to reach the end-point machine.
As a packet can and probably will pass through many routers (and network components) between the sender and receiver. If the contents of the data in that packet are sensitive – authentication information, confidential insider data – the sender would probably like to ensure that only the receiver can read the package, rather than the packet being readable by any router along the way. Secure Sockets Layer (SSL) and Transport Layer Security (TLS) are developed in order to serve this purpose in the HTTPS protocol.
HTTPS is vital to securing end-to-end interactions. For many server application, HTTPS is handled by the server side such as the Web server, TREP component (ADS) integrated with SSL Accelerator. However, the client side needs its own HTTPS implementation to make requests and to receive information securely from the server. Fortunately, Elektron-SDK Java prepares a solution for you to use the keystore file.
This article will demonstrate how to generate a new keystore file, view the keystore file’s content, import a certification along with EMA Java API walkthrough.
This article provides information and examples that aids programmers using Elektron real-time APIs (EMA and ETA) - Java Edition. It is assumed that the reader is familiar with running EMA or ETA application to connect to a provider application (or Elektron/RDF-D/ADS) before, and has experience developing products using the Java programming language in a networked environment.
The keystore file (.jsk) contains the server’s certification, including its private key which is used for cryptographic. The keystore file is protected with a password. Each keystore entry has a unique alias that refers to a particular certificate. You can administrate the keystore file using “keytool – Key and Certificate Management Tool” provided by Oracle.
For the connection and component topology that is used in this article, the consumer application connects to Advanced Distribution Server (ADS) via the Internet. The SSL accelerator is a server-side device located at the same ADS machine that helps to perform key and certificate exchange for HTTPS connection establishment.
Referring to the diagram above, if the EMA Java consumer tries to connect to the server without performing TLS handshake (RSSL_SOCKET or RSSL_HTTP), there will be no response from the server side (or encountering unexpected error) because it cannot understand a bare message, and expects a cipher message to be decrypted.
<!-- ChannelType possible values are: --> <!-- ChannelType::RSSL_SOCKET - TCP IP connection type --> <!-- ChannelType::RSSL_HTTP - Http tunnel connection type --> <!-- ChannelType::RSSL_ENCRYPTED - Https tunnel connection type --> <Channel> <Name value="Channel_4"/> <ChannelType value="ChannelType::RSSL_HTTP"/> <CompressionType value="CompressionType::None"/> <GuaranteedOutputBuffers value="5000"/> <Host value="server_host"/> <Port value="14002"/> <ObjectName value=""/> </Channel>
So, you need to specify a connection channel type to RSSL_ENCRYPTED when the server requires SSL or TLS encryption.
<Channel> <Name value="Channel_4"/> <ChannelType value="ChannelType::RSSL_ENCRYPTED"/> <CompressionType value="CompressionType::None"/> <GuaranteedOutputBuffers value="5000"/> <Host value="server_host"/> <Port value="443"/> <ObjectName value=""/> </Channel>
EMA Java API also provides a set of configuration for settings associated to the keystore file (refer to Chapter 4.3.2: Tunneling Configuration). Below are some interfaces of an OmmConsumerConfig class to specify security parameters:
|tunnelingKeyStoreFile(java.lang.String keyStoreFile)||The key store file that contains your own private keys, and public key certificates you received from someone else.|
|tunnelingKeyStorePasswd(java.lang.String keyStorePasswd)||The passwd for the key store file.|
|tunnelingKeyStoreType(java.lang.String keyStoreType)||The type of the key store for certificate file.|
Here this is the example usage to specify the keystore file and keystore password.
// Create an OMM consumer OmmConsumer consumer = EmaFactory.createOmmConsumer(EmaFactory.createOmmConsumerConfig() .consumerName("Consumer_3") .tunnelingKeyStoreFile("KEYSTORE_FILENAME") .tunnelingKeyStorePasswd("KEYSTORE_PASSWORD") );
You can find the keytool program from a bin subfolder of a Java Developer Kit (JDK) installation folder (in the same location as javac). The keytool program is a command-line based application, so you need to run it using command-prompt.
Use the following command to create a new keystore file
keytool -genkey -alias <ALIAS> -keyalg RSA -keystore <KEYSTORE_FILENAME> -storepass <PASSWORD>
The new keystore file has been created under the current working directory.
Remark: The option -genkey is the old name, but it is still supported in Java 8 release. However, the new name, -genkeypair is preferred going forward.
You can view information (and certificate, which there is no any certificate data in the new file yet) using the following command:
keytool.exe -list -v -keystore <KEYSTORE_FILENAME> -storepass <PASSWORD>
As this is the new keystore file, it does not contain any server’s certificate yet. If you try to use it, the application will receive an event indicates that it cannot initialize a channel, which is not sufficient information (see below).
Sep 24, 2018 2:45:06 PM com.thomsonreuters.ema.access.ChannelCallbackClient reactorChannelEventCallback WARNING: loggerMsg ClientName: ChannelCallbackClient Severity: Warning Text: Received ChannelDownReconnecting event on channel Channel_4 RsslReactor Channel is null Error Id 0 Internal sysError 0 Error Location Reactor.processWorkerEvent Error text Error initializing channel: errorId=0 text=null loggerMsgEnd
At this stage, you can use the JVM argument option: -Djavax.net.debug=all to print more detail of HTTPS activities. Please see the example below:
java -Djavax.net.debug=all -Djava.util.logging.config.file=logging.properties -cp <CLASSPATH> <APPLICATION_NAME>
Here this is the log output after adding the JVM parameter above:
<SSL Handshake Information> *** pool-1-thread-1, fatal error: 46: General SSLEngine problem sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target %% Invalidated: [Session-1, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384] pool-1-thread-1, SEND TLSv1.2 ALERT: fatal, description = certificate_unknown pool-1-thread-1, WRITE: TLSv1.2 Alert, length = 2 pool-1-thread-1, fatal: engine already closed. Rethrowing javax.net.ssl.SSLHandshakeException: General SSLEngine problem pool-1-thread-1, called closeOutbound() pool-1-thread-1, closeOutboundInternal()
As the client requires the keystore file with the registered certification from the server (for encryption), you may search for the server certificate using in the log output. According to our test environment (see below), it conveys that our server is using an “http://cacerts.digicert.com/DigiCertSHA2SecureServerCA.crt” during an SSL handshake stage.
*** Important updated on October 2018: The TRCC servers now use a certificate from comodo, please download it from "http://crt.comodoca.com/COMODORSAOrganizationValidationSecureServerCA.crt" instead. ***
<THIS IS THE EXAMPLE OF AN OUTPUT FROM SERVERS THAT USE DIGICERT when a -Djavax.net.debug=all JVM option is enabled> ... : ObjectId: 220.127.116.11.18.104.22.168.1 Criticality=false AuthorityInfoAccess [ [ accessMethod: ocsp accessLocation: URIName: http://ocsp.digicert.com , accessMethod: caIssuers accessLocation: URIName: http://cacerts.digicert.com/DigiCertSHA2SecureServerCA.crt ] ] <THIS IS THE EXAMPLE OF AN OUTPUT FROM SERVERS THAT USE COMODO CA when a -Djavax.net.debug=all JVM option is enabled> : ObjectId: 22.214.171.124.126.96.36.199.1 Criticality=false AuthorityInfoAccess [ [ accessMethod: caIssuers accessLocation: URIName: http://crt.comodoca.com/COMODORSAOrganizationValidationSecureServerCA.crt , accessMethod: ocsp accessLocation: URIName: http://ocsp.comodoca.com ] ]
So, you need to download this certification to your local machine (depending on which certificate that the server in your environment is using by referring to the link shown in the HTTPS/SSL or HTTPS/TLS tracing log output). After that, you can use the keytool to view and verify the content of the certification obtained using the following command:
keytool -printcert -v -file <CERTIFICATE_FILENAME>
Note: You do not have to get every certificate, just only the certificate that appears in the output during the SSL or TLS handshake stage).
The example outputs form various certifications:
To import the certification obtained into the keystore file, use the command below.
keytool -import -trustcacerts -alias <NEW_ALIAS> -file <CERTFICICATE_FILENAME> -keystore <KEYSTORE_FILENAME> -storepass <PASSWORD>
Here there are example screenshots when importing the certificate files:
Remark: The option -import is the old name but it is still supported in Java 8 release. However, the new name, -importcert is preferred going forward.
You can also re-check whether the certificate was added in the keystore file successfully or not using the same command in the previous step (and specify an alias option to filter the output if necessary).
keytool -list -v -keystore <KEYSTORE_FILENAME> -storepass <PASSWORD> -alias <ALIAS>
Below are the outputs after certification import:
After the server certificate has been entrusted within the keystore file. Now, the keystore file is ready to be used via encrypted connection type. Below is the success log output from EMA Java API.
Sep 24, 2018 3:53:49 PM com.thomsonreuters.ema.access.ChannelCallbackClient reactorChannelEventCallback INFO: loggerMsg ClientName: ChannelCallbackClient Severity: Info Text: Received ChannelUp event on channel Channel_4 Instance Name Consumer_3_1 Component Version eta3.1.1.L1.linux.rrg 64-bit Static loggerMsgEnd
Once the application can connect to the server and receive a response back. You can remove the JVM option to reduce the log overhead output.
More example from Elektron Transport API (ETA) - Java
ETA Java provides methods to specify HTTPS tunneling by setting a ConnectionTypes.ENCRYPTED constant as an input of a ConnectOptions.connectionType() method. Also, it has a TunnelingInfo class to specify details of a keystore file using (refer to Chapter 9.15: Tunneling).
|ConnectOptions||connectionType(int connectionType)||Type of connection to establish.||
|tunnelingInfo()||Tunneling connection parameters. Use this ConnectionOptions.tunnelingInfo() method to access TunnelingInfo's attributes/members.|
|tunnelingType(java.lang.String tunnelingType)||Tunneling type.||Possible values are "None", http", or "encrypted" For HTTP Tunneling, tunnelingType has to be set to "http" or "encrypted"|
|TunnelingInfo||KeystoreFile(java.lang.String KeystoreFile)||Keystore file that contains your own private keys, and public key certificates you received from someone else.||<ANY>|
|KeystorePasswd(java.lang.String KeystorePasswd)||Password for keystore file.||<ANY>|
// ConnectOptions cOpt = chnlInfo.connectOptions.connectionList().get(0).connectOptions(); cOpt.connectionType(ConnectionTypes.ENCRYPTED); cOpt.tunnelingInfo().tunnelingType("encrypted"); cOpt.tunnelingInfo().KeystoreFile("<KEYSTORE_FILENAME>"); cOpt.tunnelingInfo().KeystorePasswd("<KEYSTORE_PASSWORD>");
Example of general errors when using HTTPS with the keystore file:
Please enable the JVM option: -Djavax.net.debug=all to reveal more details about the error regarding HTTPS handshake activity.
1. The keystore file could not be found.
IOException initializeTLS: Error when loading keystore from certificate file <KEYSTORE_FILENAME> (The system cannot find the file specified)
Verify that the value of KEYSTORE_FILENAME is correct or exists or not.
2. The keystore file's password is not correct.
IOException initializeTLS: Error when loading keystore from certificate file <KEYSTORE_FILENAME> (The system cannot find the file specified)
Verify that the exact KEYSTORE_PASSWORD value is correct or not by using the keytool application.
3. The keystore file does not contain a valid certification to connect to the server.
*** pool-1-thread-1, fatal error: 46: General SSLEngine problem sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target %% Invalidated: [Session-1, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384] pool-1-thread-1, SEND TLSv1.2 ALERT: fatal, description = certificate_unknown pool-1-thread-1, WRITE: TLSv1.2 Alert, length = 2 pool-1-thread-1, fatal: engine already closed. Rethrowing javax.net.ssl.SSLHandshakeException: General SSLEngine problem pool-1-thread-1, called closeOutbound() pool-1-thread-1, closeOutboundInternal()
Check the javax.net.debug output to find the certification required.
Note: JRE8 Update 91 and higher support DigiCert certificates. If you encounter problems with DigiCert certificates, upgrade to JRE8 Update 91 or higher.
After reading this article, we hope you can get the idea about how to connect your application to the server by the HTTPS connection type. The article also introduces the Oracle's keytool application which is used for manipulating the keystore file as Java technology uses the keystore file to be a repository of certifications for secured message communication. We also mention the -Djavax.net.debug=all JVM argument which is useful when the application encounters a problem during the HTTPS connection establishment stage. The output from the JVM argument will give a meaningful message and provide some insight to identify a root cause of the problem.
- Davies, Joshua. Implementing SSL/TLS Using Cryptography and PKI. Wiley Publishing, Inc., 2011. E-book.
- Elektron Message API Java Edition V3.2.X (EMA Java) - ELEKTRON MESSAGE API DEVELOPERS GUIDE
- Transport API Java Edition V3.2.X (ETA Java) - DEVELOPERS GUIDE