Secure Communications using SSL
QuickFIX/J supports secure sockets via the Apache MINA SSL I/O filter.
The default usage of SSL is very simple. Add the following setting to your QFJ settings file:
SocketUseSSL=Y
This setting must be used for both acceptors and initiators.
Supplying SSL Contexts from the Application
By default, QuickFIX/J loads the key and trust stores named in the settings from the file system or classpath. An application can instead supply the SSLContext itself through an SSLContextProvider, for example when the stores come from a secrets manager and should stay in memory. With stores provided as Base64-encoded environment variables:
char[] password = System.getenv("FIX_KEYSTORE_PASSWORD").toCharArray();
KeyStore keyStore = KeyStore.getInstance("PKCS12");
keyStore.load(new ByteArrayInputStream(Base64.getMimeDecoder().decode(System.getenv("FIX_KEYSTORE_B64"))), password);
KeyStore trustStore = KeyStore.getInstance("PKCS12");
trustStore.load(new ByteArrayInputStream(Base64.getMimeDecoder().decode(System.getenv("FIX_TRUSTSTORE_B64"))),
System.getenv("FIX_TRUSTSTORE_PASSWORD").toCharArray());
KeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
kmf.init(keyStore, password);
TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
tmf.init(trustStore);
SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);
SocketInitiator initiator = SocketInitiator.newBuilder()
// ... application, store factory, settings
.withSSLContextProvider(sslConfig -> sslContext)
.build();
Set the provider with withSSLContextProvider on the builders of SocketInitiator, SocketAcceptor, and their threaded variants. Without a provider, QuickFIX/J loads the configured stores as before. The provider receives the SSLConfig of the session or acceptor address, so it can return different contexts, such as a client certificate per counterparty, or delegate to SSLContextFactory.getInstance(sslConfig) for stores that should still be loaded from files.
SocketUseSSL=Yis still required. The provider supplies only the context; protocols, cipher suites,NeedClientAuth, SNI, and endpoint identification are still applied from the settings, while store settings are not used.- If the provider throws a
GeneralSecurityExceptionor returnsnull, the session (initiator) or listening address (acceptor) fails to initialize, subject toContinueInitializationOnError. There is no implicit fallback to the default behavior. - The provider is called whenever an SSL filter is set up: once per listening address when an acceptor starts, and once per session when an initiator starts (and again if its I/O connector is reset). Return a new context to pick up rotated credentials on the next start, or supply a key or trust manager that reloads its material to rotate without restarting.
- Contexts created by
SSLContextFactoryhave their trust managers wrapped so that aRuntimeExceptionthrown during certificate validation is reported as aCertificateException. A supplied context is used as is; wrap its trust managers withX509TrustManagerWrapper.wrap(...)to get the same behavior.
Specific SSL Certificates
If you need to use a specific SSL certificate, configure your session like below:
SocketUseSSL=Y
SocketKeyStore=[your key store path]
SocketKeyStorePassword=[your key store password]
Client Authentication
If certificates require authentication, additional settings must be provided:
SocketTrustStore=[your trust store path]
SocketTrustStorePassword=[your trust store password]
Acceptor certificates are always authenticated by the initiator. Authenticating client certificates on the Acceptor side requires the following setting:
NeedClientAuth=Y
Example Configurations
Acceptor configuration with client certificate authentication:
[DEFAULT]
ConnectionType=acceptor
SocketAcceptHost=localhost
SocketUseSSL=Y
CipherSuites=TLS_RSA_WITH_AES_128_CBC_SHA
EnabledProtocols=TLSv1.2
SocketKeyStore=acceptor.keystore
SocketKeyStorePassword=password
NeedClientAuth=Y
[SESSION]
BeginString=FIX.4.4
SocketAcceptPort=12341
TargetCompID=ZULU1
SenderCompID=ALFA1
SocketTrustStore=acceptor1.truststore
SocketTrustStorePassword=password
Initiator configuration:
[DEFAULT]
ConnectionType=initiator
SocketConnectProtocol=SOCKET
SocketConnectHost=localhost
SocketConnectPort=12341
SocketUseSSL=Y
CipherSuites=TLS_RSA_WITH_AES_128_CBC_SHA
EnabledProtocols=TLSv1.2
SocketKeyStore=initiator1.keystore
SocketKeyStorePassword=password
SocketTrustStore=initiator1.truststore
SocketTrustStorePassword=password
[SESSION]
BeginString=FIX.4.4
TargetCompID=ALFA1
SenderCompID=ZULU1