Article

Building a keystore file to be used with an HTTPS (or ENCRYPTED) connection type for real-time Java-based APIs

Nipat Kunvutipongsak
Senior Software Engineer Senior Software Engineer

Introduction

Overview

Update: March 2025

Real-Time SDK  (i.e. EMA and ETA APIs, formerly known as Elektron SDK) 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, Real-Time Distribution System 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, Real-Time 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.

Target Audience

This article provides information and examples that aids programmers using 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 Real-Time/RDF-D/ADS) before, and has experience developing products using the Java programming language in a networked environment.

Note: Since RTSDK Java 1.5.1.L1 (EMA/ETA Java 3.5.1.L1 ), RTSDKJ Client Side uses the default Java Certificate Authority keystore location (<JAVA_HOME>/lib/security/cacerts) so a jks file isn't required.

What is the Keystore File

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.

An RSSL consumer (client-server) diagram

For the connection and component topology that is used in this article, the consumer application connects to Real-Time Advanced Distribution Server via the Internet. The SSL accelerator is a server-side device located at the same Real-Time Advanced Distribution Server machine that helps to perform key and certificate exchange for HTTPS connection establishment.

Note: The latest version of ADS supports an encryption via configurations so the SSL accelerator isn't required.

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 of the EMA Java developer guide). Below are some interfaces of an OmmConsumerConfig class to specify security parameters:

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

Note: Since RTSDK Java 1.5.1.L1 (EMA/ETA Java 3.5.1.L1 ), RTSDKJ Client Side uses the default Java Certificate Authority keystore location (<JAVA_HOME>/lib/security/cacerts) so a jks file isn't required.

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")

    );

Generate your Keystore file using Oracle's keytool

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 -genkeypair -alias <ALIAS> -keyalg RSA -keystore <KEYSTORE_FILENAME> -storepass <PASSWORD>
        
        
    
    	
            

C:\jks>"c:\Program Files\Java\jdk-21\bin\keytool.exe" -genkeypair -alias lseg -keyalg RSA -keystore lseg_keystore.jks -storepass changeit

Enter the distinguished name. Provide a single dot (.) to leave a sub-component empty or press ENTER to use the default value in braces.

What is your first and last name?

  [Unknown]:  Developers

What is the name of your organizational unit?

  [Unknown]:  Developer Advocate

What is the name of your organization?

  [Unknown]:  LSEG

What is the name of your City or Locality?

  [Unknown]:

What is the name of your State or Province?

  [Unknown]:  Bangkok

What is the two-letter country code for this unit?

  [Unknown]:  TH

Is CN=Developers, OU=Developer Advocate, O=LSEG, L=Unknown, ST=Bangkok, C=TH correct?

  [no]:  yes

 

Generating 3,072 bit RSA key pair and self-signed certificate (SHA384withRSA) with a validity of 90 days

        for: CN=Developers, OU=Developer Advocate, O=LSEG, L=Unknown, ST=Bangkok, C=TH

 

C:\jks>

The new keystore file (lseg_keystore.jks) has been created under the current working directory.

View Content in the Keystore File

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>
        
        
    
    	
            

C:\jks>"c:\Program Files\Java\jdk-21\bin\keytool.exe" -list -v -keystore lseg_keystore.jks -storepass changeit

Keystore type: PKCS12

Keystore provider: SUN

 

Your keystore contains 1 entry

 

Alias name: lseg

Creation date: Mar 27, 2025

Entry type: PrivateKeyEntry

Certificate chain length: 1

Certificate[1]:

Owner: CN=Developers, OU=Developer Advocate, O=LSEG, L=Unknown, ST=Bangkok, C=TH

Issuer: CN=Developers, OU=Developer Advocate, O=LSEG, L=Unknown, ST=Bangkok, C=TH

Serial number: a731ca149a5ed73b

Valid from: Thu Mar 27 16:54:06 ICT 2025 until: Wed Jun 25 16:54:06 ICT 2025

Certificate fingerprints:

         SHA1: 4F:44:8D:85:CF:D0:9F:FD:17:95:13:85:3F:7D:A4:9C:9C:32:6E:7A

         SHA256: 66:B9:11:AE:DF:C8:21:BF:08:C7:34:82:41:B4:78:F7:FF:E6:8A:FA:66:00:65:31:07:FB:AA:52:9C:5A:0B:B7

Signature algorithm name: SHA384withRSA

Subject Public Key Algorithm: 3072-bit RSA key

Version: 3

 

Extensions:

 

#1: ObjectId: 2.5.29.14 Criticality=false

SubjectKeyIdentifier [

KeyIdentifier [

0000: 99 39 4E 39 9C B5 DF 7E   40 C3 0C 24 D1 1D 52 90  .9N9....@..$..R.

0010: B7 EE F2 F1                                        ....

]

]

 

 

 

*******************************************

*******************************************

 

 

 

C:\jks>

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

    	
            

Feb 11, 2021 11:03:02 AM com.refinitiv.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()

Import a certificate into your keystore file

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. In this article, we will use certificates from Digicert and Sectigo

You need to download certificate files to your local machine (depending on which certificate that the server in your environment is using. 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:

Print a digitcert certificate file:

    	
            

C:\jks>"c:\Program Files\Java\jdk-21\bin\keytool.exe" -printcert -v -file DigiCertTLSRSA4096RootG5.cer

Owner: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US

Issuer: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US

Serial number: 8f9b478a8fa7eda6a333789de7ccf8a

Valid from: Fri Jan 15 07:00:00 ICT 2021 until: Mon Jan 15 06:59:59 ICT 2046

Certificate fingerprints:

         SHA1: A7:88:49:DC:5D:7C:75:8C:8C:DE:39:98:56:B3:AA:D0:B2:A5:71:35

         SHA256: 37:1A:00:DC:05:33:B3:72:1A:7E:EB:40:E8:41:9E:70:79:9D:2B:0A:0F:2C:1D:80:69:31:65:F7:CE:C4:AD:75

Signature algorithm name: SHA384withRSA

Subject Public Key Algorithm: 4096-bit RSA key

Version: 3

 

Extensions:

 

#1: ObjectId: 2.5.29.19 Criticality=true

BasicConstraints:[

  CA:true

  PathLen: no limit

]

 

#2: ObjectId: 2.5.29.15 Criticality=true

KeyUsage [

  DigitalSignature

  Key_CertSign

  Crl_Sign

]

 

#3: ObjectId: 2.5.29.14 Criticality=false

SubjectKeyIdentifier [

KeyIdentifier [

0000: 51 33 1C ED 36 40 AF 17   D3 25 CD 69 68 F2 AF 4E  Q3..6@...%.ih..N

0010: 23 3E B3 41                                        #>.A

]

]

Print a sectigo certificate file:

    	
            

C:\jks>"c:\Program Files\Java\jdk-21\bin\keytool.exe" -printcert -v -file 1720081.crt

Owner: CN=COMODO RSA Certification Authority, O=COMODO CA Limited, L=Salford, ST=Greater Manchester, C=GB

Issuer: CN=COMODO RSA Certification Authority, O=COMODO CA Limited, L=Salford, ST=Greater Manchester, C=GB

Serial number: 4caaf9cadb636fe01ff74ed85b03869d

Valid from: Tue Jan 19 07:00:00 ICT 2010 until: Tue Jan 19 06:59:59 ICT 2038

Certificate fingerprints:

         SHA1: AF:E5:D2:44:A8:D1:19:42:30:FF:47:9F:E2:F8:97:BB:CD:7A:8C:B4

         SHA256: 52:F0:E1:C4:E5:8E:C6:29:29:1B:60:31:7F:07:46:71:B8:5D:7E:A8:0D:5B:07:27:34:63:53:4B:32:B4:02:34

Signature algorithm name: SHA384withRSA

Subject Public Key Algorithm: 4096-bit RSA key

Version: 3

 

Extensions:

 

#1: ObjectId: 2.5.29.19 Criticality=true

BasicConstraints:[

  CA:true

  PathLen: no limit

]

 

#2: ObjectId: 2.5.29.15 Criticality=true

KeyUsage [

  Key_CertSign

  Crl_Sign

]

 

#3: ObjectId: 2.5.29.14 Criticality=false

SubjectKeyIdentifier [

KeyIdentifier [

0000: BB AF 7E 02 3D FA A6 F1   3C 84 8E AD EE 38 98 EC  ....=...<....8..

0010: D9 32 32 D4                                        .22.

]

]

 

To import the certification obtained into the keystore file, use the command below.

    	
            keytool -importcert -alias <NEW_ALIAS> -file <CERTFICICATE_FILENAME> -keystore <KEYSTORE_FILENAME> -storepass <PASSWORD>
        
        
    

Import a digicert certificate file.

    	
            

C:\jks>"c:\Program Files\Java\jdk-21\bin\keytool.exe" -importcert -alias digicert -file DigiCertTLSRSA4096RootG5.cer -keystore lseg_keystore.jks -storepass changeit

Owner: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US

Issuer: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US

Serial number: 8f9b478a8fa7eda6a333789de7ccf8a

Valid from: Fri Jan 15 07:00:00 ICT 2021 until: Mon Jan 15 06:59:59 ICT 2046

Certificate fingerprints:

         SHA1: A7:88:49:DC:5D:7C:75:8C:8C:DE:39:98:56:B3:AA:D0:B2:A5:71:35

         SHA256: 37:1A:00:DC:05:33:B3:72:1A:7E:EB:40:E8:41:9E:70:79:9D:2B:0A:0F:2C:1D:80:69:31:65:F7:CE:C4:AD:75

Signature algorithm name: SHA384withRSA

Subject Public Key Algorithm: 4096-bit RSA key

Version: 3

 

Extensions:

 

#1: ObjectId: 2.5.29.19 Criticality=true

BasicConstraints:[

  CA:true

  PathLen: no limit

]

 

#2: ObjectId: 2.5.29.15 Criticality=true

KeyUsage [

  DigitalSignature

  Key_CertSign

  Crl_Sign

]

 

#3: ObjectId: 2.5.29.14 Criticality=false

SubjectKeyIdentifier [

KeyIdentifier [

0000: 51 33 1C ED 36 40 AF 17   D3 25 CD 69 68 F2 AF 4E  Q3..6@...%.ih..N

0010: 23 3E B3 41                                        #>.A

]

]

 

Trust this certificate? [no]:  yes

Certificate was added to keystore

 

C:\jks>

Import a sectigo certificate file.

    	
            

C:\jks>"c:\Program Files\Java\jdk-21\bin\keytool.exe" -importcert -alias sectigo -file 1720081.crt -keystore lseg_keystore.jks -storepass changeit

Owner: CN=COMODO RSA Certification Authority, O=COMODO CA Limited, L=Salford, ST=Greater Manchester, C=GB

Issuer: CN=COMODO RSA Certification Authority, O=COMODO CA Limited, L=Salford, ST=Greater Manchester, C=GB

Serial number: 4caaf9cadb636fe01ff74ed85b03869d

Valid from: Tue Jan 19 07:00:00 ICT 2010 until: Tue Jan 19 06:59:59 ICT 2038

Certificate fingerprints:

         SHA1: AF:E5:D2:44:A8:D1:19:42:30:FF:47:9F:E2:F8:97:BB:CD:7A:8C:B4

         SHA256: 52:F0:E1:C4:E5:8E:C6:29:29:1B:60:31:7F:07:46:71:B8:5D:7E:A8:0D:5B:07:27:34:63:53:4B:32:B4:02:34

Signature algorithm name: SHA384withRSA

Subject Public Key Algorithm: 4096-bit RSA key

Version: 3

 

Extensions:

 

#1: ObjectId: 2.5.29.19 Criticality=true

BasicConstraints:[

  CA:true

  PathLen: no limit

]

 

#2: ObjectId: 2.5.29.15 Criticality=true

KeyUsage [

  Key_CertSign

  Crl_Sign

]

 

#3: ObjectId: 2.5.29.14 Criticality=false

SubjectKeyIdentifier [

KeyIdentifier [

0000: BB AF 7E 02 3D FA A6 F1   3C 84 8E AD EE 38 98 EC  ....=...<....8..

0010: D9 32 32 D4                                        .22.

]

]

 

Trust this certificate? [no]:  yes

Certificate was added to keystore

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>
        
        
    

View the digicert certificate:

    	
            

C:\jks>"c:\Program Files\Java\jdk-21\bin\keytool.exe" -list -v -alias digicert -keystore lseg_keystore.jks -storepass changeit

Alias name: digicert

Creation date: Mar 27, 2025

Entry type: trustedCertEntry

 

Owner: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US

Issuer: CN=DigiCert TLS RSA4096 Root G5, O="DigiCert, Inc.", C=US

Serial number: 8f9b478a8fa7eda6a333789de7ccf8a

Valid from: Fri Jan 15 07:00:00 ICT 2021 until: Mon Jan 15 06:59:59 ICT 2046

Certificate fingerprints:

         SHA1: A7:88:49:DC:5D:7C:75:8C:8C:DE:39:98:56:B3:AA:D0:B2:A5:71:35

         SHA256: 37:1A:00:DC:05:33:B3:72:1A:7E:EB:40:E8:41:9E:70:79:9D:2B:0A:0F:2C:1D:80:69:31:65:F7:CE:C4:AD:75

Signature algorithm name: SHA384withRSA

Subject Public Key Algorithm: 4096-bit RSA key

Version: 3

 

Extensions:

 

#1: ObjectId: 2.5.29.19 Criticality=true

BasicConstraints:[

  CA:true

  PathLen: no limit

]

 

#2: ObjectId: 2.5.29.15 Criticality=true

KeyUsage [

  DigitalSignature

  Key_CertSign

  Crl_Sign

]

 

#3: ObjectId: 2.5.29.14 Criticality=false

SubjectKeyIdentifier [

KeyIdentifier [

0000: 51 33 1C ED 36 40 AF 17   D3 25 CD 69 68 F2 AF 4E  Q3..6@...%.ih..N

0010: 23 3E B3 41                                        #>.A

]

]

View the sectigo certificate:

    	
            

C:\jks>"c:\Program Files\Java\jdk-21\bin\keytool.exe" -list -v -alias sectigo -keystore lseg_keystore.jks -storepass changeit

Alias name: sectigo

Creation date: Mar 27, 2025

Entry type: trustedCertEntry

 

Owner: CN=COMODO RSA Certification Authority, O=COMODO CA Limited, L=Salford, ST=Greater Manchester, C=GB

Issuer: CN=COMODO RSA Certification Authority, O=COMODO CA Limited, L=Salford, ST=Greater Manchester, C=GB

Serial number: 4caaf9cadb636fe01ff74ed85b03869d

Valid from: Tue Jan 19 07:00:00 ICT 2010 until: Tue Jan 19 06:59:59 ICT 2038

Certificate fingerprints:

         SHA1: AF:E5:D2:44:A8:D1:19:42:30:FF:47:9F:E2:F8:97:BB:CD:7A:8C:B4

         SHA256: 52:F0:E1:C4:E5:8E:C6:29:29:1B:60:31:7F:07:46:71:B8:5D:7E:A8:0D:5B:07:27:34:63:53:4B:32:B4:02:34

Signature algorithm name: SHA384withRSA

Subject Public Key Algorithm: 4096-bit RSA key

Version: 3

 

Extensions:

 

#1: ObjectId: 2.5.29.19 Criticality=true

BasicConstraints:[

  CA:true

  PathLen: no limit

]

 

#2: ObjectId: 2.5.29.15 Criticality=true

KeyUsage [

  Key_CertSign

  Crl_Sign

]

 

#3: ObjectId: 2.5.29.14 Criticality=false

SubjectKeyIdentifier [

KeyIdentifier [

0000: BB AF 7E 02 3D FA A6 F1   3C 84 8E AD EE 38 98 EC  ....=...<....8..

0010: D9 32 32 D4                                        .22.

]

]

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.

    	
            

Feb 11, 2021 11:04:33 AM com.refinitiv.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 ads3.4.2.L1.linux.tis.rrg 64-bit

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 Enterprise 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 of the ETA Java developer guide).

Class Method Purpose Value
ConnectOptions connectionType(int connectionType) Type of connection to establish.
  • ConnectionTypes.ENCRYPTED
    • Indicates that the Channel is using an SSL/TLS encrypted HTTP TCP-based socket connection.
  • ConnectionTypes.HTTP
    • Indicates that the Channel is using an HTTP TCP-based socket connection.
  • ConnectionTypes.RELIABLE_MCAST
    • Indicates that the Channel is using a reliable multicast based connection.
  • ConnectionTypes.SEQUENCED_MCAST 
  • ConnectionTypes.SOCKET
    • Indicates that the Channel is using a standard TCP-based socket connection.
  • ConnectionTypes.UNIDIR_SHMEM
    • Indicates that the Channel is using a unidirectional shared memory connection.
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>

Example:

    	
            

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

Error Message:

 

    	
            IOException initializeTLS: Error when loading keystore from certificate file <KEYSTORE_FILENAME> (The system cannot find the file specified)
        
        
    
Resolution:

Verify that the value of KEYSTORE_FILENAME is correct or exists or not.

2. The keystore file's password is not correct.

Error Message:
    	
            IOException initializeTLS: Error when loading keystore from certificate file <KEYSTORE_FILENAME> (The system cannot find the file specified)
        
        
    
Resolution:

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.

Error Message:
    	
            

***

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

Resolution:

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.

 

Conclusion

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.

 

Reference:

For any questions related to this article or the Real-Time SDK Java page, please use the Developer Community Q&A Forum.