How to setup secure SSL/TLS connесtion between FIXEdge, FIXICC-agent and FIXICC
Overview
This article shows how to configure a secure connection between FIXEdge's parties as on a diagram below:
- FIXEdge side. Establish SSL connection to LDAP service (out of scope)
- LDAP Service side. Accept connection from FIXEdge (out of scope)
- LDAP Service side. Accept connection from FIXICC-agent (out of scope)
- FIXICC-agent side. Establish SSL connection to LDAP service
- FIXEdge side. Accept SSL connection from FIXICC-agent
- FIXICC-agent side. Establish SSL connection to FIXEdge
- FIXICC-agent side. Accept SSL connections.
- FIXICC GUI side. Establish SSL connections.
- Enable SSL connections between FIXEdge and FIX-clients
FIXEdge uses OpenSSL for a secure connection.
FIXICC and FIXICC-agent package includes and run on JRE 1.8.x. Java Virtual Machine determines which secure layer to use, in Java 8 it is TLS 1.2 by default.
Enabling SSL/TLS connection in java applications (FIXICC GUI, FIXICC-agent)
In order to establish SSL/TLS connection between two java applications, one can use KeyStores and TrustStores:
- KeyStore is used for storing of private keys and certificates. It's commonly used on the server-side.
- TrustStore is used for storing trusted certificates and public keys for trusted certificate authorities CA and self-signed certificates. It's commonly used on the client-side.
keytool is a official java tool for keys and certificates management. Here is an example of how to create these storages by using keytool that is part of J2SE SDK(http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html).
Manage KeyStores and TrustStores
The following steps allow creating necessary containers for certificates and keys which would be used for establishing SSL Connections between applications.
Create KeyStore with the certificate
Create a new KeyStore containing a certificate and a private key.
keytool -keystore fixiccKeystore.key -genkey -alias fixicc
Note:
sslKeystoreKeyAlias is case-sensitive, but the Keytool saves upper case letters to the alias only when parameter -storetype CaseExactJKS is given while creating the KeyStore.
The program will ask for certificate owner information and request to enter a password for the KeyStore.
fixiccKeystore.key - is a resulted KeyStore file.
Export certificate from KeyStore
Export the public certificate using keytool.
keytool -export -keystore fixiccKeystore.key -alias fixicc -rfc -file fixicc.cer
The program will request a password <keystore_password> for fixiccKeystore.key which was entered during "Create KeyStore with the certificate" step.
Import certificate to TrustStore
Import public certificate to TrustStore
keytool -import -file fixicc.cer -alias fixiccUI -keystore fixiccTrustStore.key
The program will ask for a new password for Trust store and if the certificate is trusted.
SSL/TLS Connection Configuration
Enable SSL connections between FIXICC-agent and FIXICC GUI
FIXICC-agent side. Accept SSL connections.
Enable SSL connections in agent.properties:
AgentServerEnableSSL=true
Use private key and certificate from KeyStore. Pass additional JVM parameters as wrapper parameters in wrapper.conf:
wrapper.java.additional.3=-Djavax.net.ssl.keyStore=${wrapper_home}/FIXEdge1.fixicc-agent/conf/fixiccKeystore.key
wrapper.java.additional.4=-Djavax.net.ssl.keyStorePassword=<keystore_password>
where
${wrapper_home}/FIXEdge1.fixicc-agent/conf/fixiccKeystore.key - the path to keyStore
<keystore_password> - the password for keyStore
FIXICC GUI side. Establish SSL connections.
Enable SSL connections in fixengine.properties
enableSSL=true
Use certificate from TrustStore for establishing a connection. Pass additional JVM parameters as 'default_options' parameters in fixicc.conf:
default_options="<OTHER_PRAMETERS> -J-Djavax.net.ssl.trustStore=etc/fixiccTrustStore.key -J-Djavax.net.ssl.trustStorePassword=<truststore_password>"
where
etc/fixiccTrustStore.key - the path to trustStore
<truststore_password> - the password for trustStore
Enable SSL connections between FIXICC-agent and FIXEdge (Version 1)
This version of configuration is based on instructing FIXICC Agent to use FIXEdge's ListenSSLPort to connect.
FIXICC-agent side. Establish SSL connection to FIXEdge
Enable SSL initiator connections in fixengine.properties:
enableSSL=true
Set remote port parameter name in fixicc-agent to SSL port configured in FIXEdge that should be used for SSL connection (i.e. ListenSSLPort from engine.properties)
EngineProperty.AdminSessionPort = ListenSSLPort
Import FIXEdge public certificate (see SSLCertificate parameter value from engine.properties) to TrustStore
keytool -import -file fixedge.crt -alias fixedgeSrv -keystore fixiccTrustStore.key
Use certificate from TrustStore for establishing a connection. Pass additional JVM parameters as wrapper parameters in wrapper.conf
wrapper.java.additional.5=-Djavax.net.ssl.trustStore=${wrapper_home}/FIXEdge1.fixicc-agent/conf/fixiccTrustStore.key
wrapper.java.additional.6=-Djavax.net.ssl.trustStorePassword=<truststore_password>
where
${wrapper_home}/FIXEdge1.fixicc-agent/conf/fixiccTrustStore.key - the path to trustStore
<truststore_password> - the password for trustStore
FIXEdge side. Accept SSL connection from FIXICC-agent
Enable SSL connections in engine.properties:
ListenSSLPort = 8905 SSLCertificate = FIXEdge1/conf/cert.pem SSLPrivateKey = FIXEdge1/conf/key.pem SSLProtocols = TLSv1_2
where
FIXEdge1/conf/cert.pem - certificate
FIXEdge1/conf/key.pem - private.key
For key and cert files please set required privileges: FIXEdge installation with the principle of least privilege on Linux
For details please refer to:
Enable SSL connections between FIXICC-agent and FIXEdge (Version 2)
This second version is based on Monitoring.Listen port usage on FIXEdge side. Secure connection in this case is achieved by setting Monitoring.ListenPort equal to ListenSSLPort
FIXICC-agent side. Establish SSL connection to FIXEdge
Enable SSL initiator connections in fixengine.properties:
enableSSL=true
Import FIXEdge public certificate (see SSLCertificate parameter value from engine.properties) to TrustStore
keytool -import -file fixedge.crt -alias fixedgeSrv -keystore fixiccTrustStore.key
Use certificate from TrustStore for establishing a connection. Pass additional JVM parameters as wrapper parameters in wrapper.conf
wrapper.java.additional.5=-Djavax.net.ssl.trustStore=${wrapper_home}/FIXEdge1.fixicc-agent/conf/fixiccTrustStore.key
wrapper.java.additional.6=-Djavax.net.ssl.trustStorePassword=<truststore_password>
where
${wrapper_home}/FIXEdge1.fixicc-agent/conf/fixiccTrustStore.key - the path to trustStore
<truststore_password> - the password for trustStore
FIXEdge side. Accept SSL connection from FIXICC-agent
Enable SSL connections in engine.properties:
ListenSSLPort = 8905 SSLCertificate = FIXEdge1/conf/cert.pem SSLPrivateKey = FIXEdge1/conf/key.pem SSLProtocols = TLSv1_2 Monitoring.ListenPort = 8905
where
FIXEdge1/conf/cert.pem - certificate
FIXEdge1/conf/key.pem - private.key
For key and cert files please set required privileges: FIXEdge installation with the principle of least privilege on Linux
For details please refer to:
Enable SSL connections between FIXICC-agent and LDAP service
FIXICC-agent side. Establish SSL connection to LDAP service
Enable SSL initiator connections in fixengine.properties:
enableSSL=true
Import LDAP server public certificate to TrustStore
keytool -import -file ldap.crt -alias ldapSrv -keystore fixiccTrustStore.key
Use certificate from TrustStore for establishing a connection. Pass additional JVM parameters as wrapper parameters in wrapper.conf
wrapper.java.additional.7=-Djavax.net.ssl.trustStore=${wrapper_home}/FIXEdge1.fixicc-agent/conf/fixiccTrustStore.key
wrapper.java.additional.8=-Djavax.net.ssl.trustStorePassword=<truststore_password>
where
${wrapper_home}/FIXEdge1.fixicc-agent/conf/fixiccTrustStore.key - the path to trustStore
<truststore_password> - the password for trustStore
LDAP Service side. Accept connection from FIXICC-agent
Out of the scope of this article.
Enable SSL connections between FIXEdge and FIX-clients
Information can be found in the articles:
- How to configure built-in SSL support for FIX sessions in FIXEdge
- How to use SSL with FIX Antenna C++ and FIX Antenna .NET
In case if FIX Client doesn't have SSL support in the applications, proxies application like STunnel can be used for it.
See an example of the configuration here: How to configure stunnel to enable SSL for FIX session#InitiatorFIXsession
Enable SSL connections between FIXEdge and LDAP service
Out of the scope of this article.
Troubleshooting
FIXICC-agent. SSL debugging
wrapper.java.additional.9=-Djavax.net.debug=ssl
After setting up configuration you need to restart the FIXICC Agent. Please check the log file and make sure that the FIXICC Agent started without errors.
Unknown error
To get the reason of unknown errors like below:
error:1408A0C1:lib(20):func(138):reason(193). Unknown error 336109761. (Error code = 336109761)
run openssl application for error number 1408A0C1
openssl errstr 1408A0C1
or check the error code meaning reason(193). e.g.: on site
FIXEdge rejects SSL connection from FIXICC-agent
The administrative session from FIXICC-agent is rejected when it is trying to connect over SSL to SSL port with reason:
Administrative client is rejected: connect port of the client (8905) is different from expected (8900).
where:
- 8905 - port accepting SSL connection. See ListenSSLPort parameter.
- 8900 - target port for FIXICC-agent administration session defined in EngineProperty.AdminSessionPort parameter in agent.properties. See FIXICC-agent side. Establish SSL connection to FIXEdge for details.
It can be solved with removing, commenting the property Monitoring.ListenPort in engine.properties or setting it equal to ListenSSLPort (see Enable SSL connections between FIXICC-agent and FIXEdge (Version2))
In case of removing (commenting) Monitoring.ListenPort accepting connections of administrative sessions to this port stops to work. Non SSL admistrative sessions can be connected to ports from ListenPort parameter in engine.properties.
An example of error output in FIXEdge or FIX Antenna logs:
<time> Severity=INFO Category=Engine Incoming TCP connection was detected (from 127.0.0.1:56896). <time> Severity=WARN Category=Engine Session <FIXADMIN, AdminClient> : Error during processing Logon message from 127.0.0.1:56896: Administrative client is rejected: connect port of the client (8905) is different from expected (8900). <time> Severity=INFO Category=Engine Incoming TCP connection was closed (from 127.0.0.1:56896).
An example of error output in FIXICC-agent logs: