OnixS C++ FIX Engine 4.14.0
Users' manual and API documentation
Loading...
Searching...
No Matches
Using TLS/SSL Encryption in Session Connections

For security in FIX messaging, C++ FIX Engine provides the ability to encrypt FIX connections with the SSL (Secure Sockets Layer) or TLS (Transport Layer Security) protocols. SSL v3.0, TLS v1.0, v1.1, v1.2, v1.3 are supported. The actual protocol and version are chosen automatically by a server side during the TLS/SSL Handshake. The client sends the highest version number that is supported and the server sends the highest version number that is supported by both sides. This is the protocol version that will be used during the connection.

Encrypting FIX Connections with TLS/SSL

Enabling TLS encrypts the connection, but does not enable certificate verification. SSL.VerifyPeer is false by default. To verify the counterparty's certificate, configure peer verification and the trusted CA file before connecting.

Initial Evaluation

For a first connection to a controlled test endpoint, you can evaluate TLS encryption without provisioning a trusted CA file. This path does not verify the server's certificate; use it only in a controlled test environment without production credentials or traffic.

  1. Before Engine initialization, leave the Engine-level SSL.VerifyPeer at its default false, or explicitly set it to false in your evaluation configuration. Initialize the Engine as described in Engine Initialization and Shutdown.
  2. Create an initiator session, set OnixS::FIX::Session::encryptionMethod to OnixS::FIX::EncryptionMethod::SSL, and set OnixS::FIX::Session::sslVerifyPeer(false). Both Engine and session verification must be disabled: session false cannot override Engine true. A trusted CA file is not required for this path.
  3. Configure SNI if the endpoint requires it; see Server Name Indication (SNI). The server still needs a certificate and private key. If it requires mutual TLS, you must also supply the client credentials described in Optional Client Credentials for Mutual TLS.
  4. Call OnixS::FIX::Session::logonAsInitiator with the test host and port. For initial testing, pass true as setResetSeqNumFlag, as in the example below, to send ResetSeqNumFlag(141)=Y and request that both sides reset sequence numbers. Follow the counterparty's reset policy; see Resetting Message Sequence Numbers via ResetSeqNumFlag Field.
  5. Exchange test messages, then call OnixS::FIX::Session::logout and OnixS::FIX::Session::shutdown.

The following snippet assumes that the Engine is initialized with SSL.VerifyPeer=false and that the test endpoint requires neither SNI nor client credentials. Replace the host, port, and CompIDs with your test endpoint's values.

const std::string SenderCompID = "Sender";
const std::string TargetCompID = "Target";
const std::string Host = "TargetHost";
const int Port = 443;
const bool ResetSequenceNumbersForInitialTesting = true;
// Initialize the Engine with SSL.VerifyPeer=false before running this evaluation snippet.
Session session(SenderCompID, TargetCompID, ProtocolVersion::FIX_42, nullptr);
// Controlled evaluation only: encrypt traffic without verifying the server's certificate.
session.encryptionMethod(EncryptionMethod::SSL);
session.sslVerifyPeer(false);
// Send ResetSeqNumFlag(141)=Y to request that both sides reset sequence numbers for initial testing.
session.logonAsInitiator(Host, Port, ResetSequenceNumbersForInitialTesting);
// Test message exchange goes here.
session.logout("TLS/SSL evaluation is finished.").shutdown();

Before production use, configure trust and enable peer verification as shown in Connection with Certificate Verification. Also review the identity limitations in What Peer Verification Checks.

Configure Certificate Verification

For an initiator session with certificate verification:

  1. Initialize the Engine as described in Engine Initialization and Shutdown. Obtain the trusted CA certificates for the counterparty through your agreed provisioning process and store them in a PEM file readable by the application.
  2. Create the session and set OnixS::FIX::Session::encryptionMethod to OnixS::FIX::EncryptionMethod::SSL.
  3. Enable OnixS::FIX::Session::sslVerifyPeer and set OnixS::FIX::Session::sslCaFile to the trusted CA file. If the per-session CA file is unset, the Engine-level SSL.CaFile is used. These settings can also be configured globally through OnixS::FIX::EngineSettings or the configuration file.
  4. If the counterparty requires a client certificate, configure the client certificate and private key as described in Optional Client Credentials for Mutual TLS below.
  5. Establish the FIX connection with OnixS::FIX::Session::logonAsInitiator.

What Peer Verification Checks

Peer verification checks the certificate chain against the configured trust and rejects certificate validation failures, such as an untrusted issuer or an expired certificate. It does not match the certificate to the connection's hostname or to a FIX CompID. A successful TLS handshake therefore must not be interpreted as proof of either identity match.

For production, use the CA certificates obtained through the agreed provisioning process described in Configure Certificate Verification. Where available, scope the CA file to an issuer used only for the intended counterparty's FIX service, rather than a general public CA bundle. Any otherwise valid certificate issued by a trusted CA can pass chain verification, including certificates for other parties if that CA also issues them.

Server Name Indication (SNI)

If the counterparty requires SNI to select its TLS endpoint, set OnixS::FIX::Session::sslClientSni before connecting. An explicit value supplies the server name; "*" uses the connection URL. With "*", the connection URL must be a DNS name, not an IP address. SNI selects the server name sent in the handshake; it does not enable hostname verification.

Connection with Certificate Verification

This example assumes that the Engine is initialized and that the trusted CA file is available. Replace the host, port, CompIDs, and file path with the values agreed with your counterparty. For what this verification does and does not check, see What Peer Verification Checks.

const std::string SenderCompID = "Sender";
const std::string TargetCompID = "Target";
const std::string Host = "TargetHost";
const int Port = 443;
const std::string TrustedCaFile = "trusted-ca.pem";
const bool ResetSequenceNumbersForInitialTesting = true;
Session session(SenderCompID, TargetCompID, ProtocolVersion::FIX_42, nullptr);
// Verify the server's certificate against the configured trust before exchanging FIX messages.
session.encryptionMethod(EncryptionMethod::SSL);
session.sslVerifyPeer(true);
session.sslCaFile(TrustedCaFile);
// Send ResetSeqNumFlag(141)=Y to request that both sides reset sequence numbers for initial testing.
session.logonAsInitiator(Host, Port, ResetSequenceNumbersForInitialTesting);
// Message exchange goes here.
session.logout("TLS/SSL connection is finished.").shutdown();

The example sets ResetSeqNumFlag(141)=Y in the initial Logon to request that both sides reset sequence numbers during initial testing. Production reconnects normally preserve sequence numbers; reset them only according to the counterparty's agreed policy. See Resetting Message Sequence Numbers via ResetSeqNumFlag Field for the flag's behavior and venue constraints.

Optional Client Credentials for Mutual TLS

A trusted CA file identifies which issuers to trust when verifying the counterparty. A client certificate and private key identify your application to a counterparty that requires mutual TLS. They are not required merely to verify the server's certificate.

Before logon, set both OnixS::FIX::Session::sslCertificateFile and OnixS::FIX::Session::sslPrivateKeyFile. They may reference the same PEM file if it contains both items. For an encrypted private key, also set OnixS::FIX::Session::sslPrivateKeyPassword, which accepts an OnixS::Cryptography::SecureString supplied by the application.

The certificate file can also contain a certificate chain with multiple CA certificates; see SSL.CertificateFile in Complete Reference of Configuration Settings. Chain-file loading applies only when no CA file is configured (including the Engine-level fallback for initiators). With the explicit CA configuration above, the certificate file is loaded as a single certificate.

Call this helper before logonAsInitiator when client credentials are required. Its password argument comes from the application's credential handling; no password is embedded in the example.

void configureTlsClientCredentials(OnixS::FIX::Session & session,
const OnixS::Cryptography::SecureString & privateKeyPassword)
{
const std::string ClientCertificateFile = "client-certificate.pem";
const std::string ClientPrivateKeyFile = "client-private-key.pem";
// Supply the client's identity when the counterparty requires mutual TLS.
session.sslCertificateFile(ClientCertificateFile);
session.sslPrivateKeyFile(ClientPrivateKeyFile);
// This helper assumes an encrypted private key; the application supplies its password.
session.sslPrivateKeyPassword(privateKeyPassword);
}

Acceptor Configuration

Per-session TLS settings are supported only for initiators. Acceptors use the global Engine settings:

  • Configure SSL.ListenPort, SSL.CertificateFile, and SSL.PrivateKeyFile before Engine initialization. Set SSL.PrivateKeyPassword as well if the acceptor's private key is encrypted.
  • To require mutual TLS, enable SSL.VerifyPeer and configure SSL.CaFile with the CA certificates trusted to issue client certificates. The acceptor then rejects an initiator that supplies no client certificate or whose certificate fails verification. The initiator's CA file only controls its verification of the server; it does not satisfy the acceptor's client-certificate requirement.

Create the acceptor session, select OnixS::FIX::EncryptionMethod::SSL, and call OnixS::FIX::Session::logonAsAcceptor. See Per-session TLS/SSL Settings for initiator settings and their Engine-level fallback, and Troubleshooting for connection failures.

Limit the TLS/SSL protocol versions

By default, a server side automatically chooses the actual TLS/SSL protocol and version during the TLS/SSL Handshake. However, some erroneous or more restricted servers, which allow only the specific protocol version, can reject TLS/SSL connections acting in such an algorithm. In such cases, the client can limit the TLS/SSL protocol versions to be used. For this purpose, SSL.MinProtocolVersion and SSL.MaxProtocolVersion parameters of Engine configuration settings can be used. Also, there are corresponding session-level OnixS::FIX::Session::sslMinProtocolVersion and OnixS::FIX::Session::sslMaxProtocolVersion settings:

const std::string SenderCompID = "Sender";
const std::string TargetCompID = "Target";
const std::string Host = "TargetHost";
const int Port = 443;
const std::string TrustedCaFile = "trusted-ca.pem";
const bool ResetSequenceNumbersForInitialTesting = true;
Session session(SenderCompID, TargetCompID, ProtocolVersion::FIX_42, nullptr);
// Limit the given session to use the TLS v1.2 version only.
// Certificate verification is required independently of protocol version selection.
session.sslVerifyPeer(true);
session.sslCaFile(TrustedCaFile);
// Send ResetSeqNumFlag(141)=Y to request that both sides reset sequence numbers for initial testing.
session.logonAsInitiator(Host, Port, ResetSequenceNumbersForInitialTesting);
// Message exchange goes here.
session.logout("TLS/SSL connection is finished.").shutdown();
Note
It is not recommended to limit the TLS/SSL protocol versions in normal cases since it can prevent using the most secure available protocol version. Therefore, it should be used only when the default method does not work.
See also
The "SIGPIPE Linux signal" article on the Troubleshooting page