1. Paxos Crypto Brokerage
  2. Support & Troubleshooting

Troubleshooting FIX mTLS connectivity configuration

Context:

Paxos uses mTLS connection between FIX Server and Clients. The onboarding procedure requires a certificate to be generated for the FIX Client and configured on both the server side (Paxos) the client side to support the FIX integration.

Please refer to the following troubleshooting steps if unable to connect after the initial configuration is completed on the server side.

 

Troubleshooting Steps:

1) Verify the id the certificate can be validated by the CA file:

openssl verify -CAfile ca.crt fix.itbit.pem

fix.itbit.pem: OK

If the command doesn't return "fix.itbit.pem: OK", it means that the certificate cannot be validated by the ca file and it won't be possible to establish the connection using these files. You can try to find a solution on how to verify and fix the files, or regenerate the certificates. If a new ca.crt is generated, it will be required to update the configuration on the Paxos server before the connection can be retried.

 

2) Verify certificate chain

This is only applicable if you are using a certificate signed by a CA (certificate authority), rather than a self-signed certificate.

Run the command to output the Subject and the Issuer from the certificate: 

openssl x509 -text -in ca.crt | grep -E '(Subject|Issuer):'

The file must contain a complete chain of all intermediate CA's certificates (where "Issuer" equals to "Subject" of the next certificate) and end with the ROOT certificate (has the same "Issuer" and "Subject"). 

 

3) Verify connectivity to the server using telnet utility:

telnet sandbox-fix.itbit.com 4490


Trying 18.210.66.68...
Connected to sandbox-fix.itbit.com.
Escape character is '^]'.

Please use the FIX server address and port provided by Paxos during onboarding.

If the command doesn't show that you are connected to the server, you are either connecting to a wrong server:port, or the connection may be blocked by your corporate firewall.

 

4) Test if the connection works using OpenSSL commands:

Run the following command to verify the connection between the FIX Server and the Client. Please use the FIX server address and port provided by Paxos during onboarding.

openssl s_client -connect sandbox-fix.itbit.com:4490 -key fix.itbit.pem -cert fix.itbit.pem -CAfile itbit-ca.pem 
  • The following errors in the output of the openssl command indicates an issue with the certificate in fix.itbit.pem. Refer to the next steps for recommendations on how to validate the content of fix.itbit.pem file.
SSL3 alert read:fatal:handshake failure
SSL_connect:error in error
40263D5CF87F0000:error:0A000410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure:ssl/record/rec_layer_s3.c:1586:SSL alert number 40
  • The following error in the command output indicates that itbit-ca.pem is invalid. Save the content of of the certificate provided on the onboarding page into itbit-ca.pem to resolve the issue.
verify error:num=19:self-signed certificate in certificate chain
  • If the following message is generated by the OpenSSL command and there are no "error" messages in the output - generated certificate files are valid the connection and the issue with connectivity can be due to the FIX client or the proxy  misconfiguration. Please refer to the next steps to validate the configuration.
---
SSL handshake has read 4187 bytes and written 2429 bytes
Verification: OK
---

Please note that you may see this message when itbit-ca.pem is properly set but fix.itbit.pem file is invalid. Please check for other errors in the output as provided in the examples above!

 

5) Verify the expected content of the generated files:

  • Here is the list of files you should see after executing the commands outlined in the onboarding procedure and saving the content of the Paxos server certificate into itbit-ca.pem:
ca.key
ca.crt
host.key
host.csr
host.crt
fix.itbit.pem
itbit-ca.pem
  • To configure your FIX client, you will need to update these two (2) files:
itbit-ca.pem
fix.itbit.pem
  • Here is an example of expected content for each file:
    • fix.itbit.pem (this is just a copy of host.crt and host.key merged into a single file).
-----BEGIN CERTIFICATE-----
MIIFUTCCAzkCFGZE+l0Tx8RVS7z7JkHHu7ppjSZCMA0GCSqGSIb3DQEBCwUAMGMx
...
84DxImyoe554wsw6rxiFdyV/IX6b
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
MIIJQwIBADANBgkqhkiG9w0BAQEFAASCCS0wggkpAgEAAoICAQCRzrd5mdhB2Efe
...
lzHutyBZunsJ+fP6kBQ73gjj3Nu/JiM=
-----END PRIVATE KEY-----
    • itbit-ca.pem  (content of this file should be copied from the onboarding page)
-----BEGIN CERTIFICATE-----
MIIDMTCCAhmgAwIBAgIUWhpRwwUwRO2IjZ4fHCrvrr5sYe8wDQYJKoZIhvcNAQEL
...
lBC1p6TPtCEF1uClT/OqipKPcycrkEskeJuJgpLVe1V1qkRfY6Yai+a1C9D1myl1
HAWLatk=
-----END CERTIFICATE-----

 

The rest of the files are not required for the connection. The following serves as as reference for what each file is for:

    • ca.key (do not share the private key with Paxos or anyone else!)
-----BEGIN PRIVATE KEY-----
MIIJQgIBADANBgkqhkiG9w0BAQEFAASCCSwwggkoAgEAAoICAQCT5YaxDb/g4YXX
...
8P7oMPDrT1BLQ7xwE5Kf4nFWA9zLsg==
-----END PRIVATE KEY-----
    • ca.crt (this file has to be sent to Paxos and it will be used on the server to validate the connection from the client. Valid for 1000 days.)
-----BEGIN CERTIFICATE-----
MIIFpzCCA4+gAwIBAgIUF/WS1S5qYS5B+BIIANxjdxTuGu4wDQYJKoZIhvcNAQEL
...
FFlFkbkIR2HBnxI=
-----END CERTIFICATE-----
    • host.key (do not share the private key with Paxos or anyone else!)
-----BEGIN PRIVATE KEY-----
MIIJQwIBADANBgkqhkiG9w0BAQEFAASCCS0wggkpAgEAAoICAQCRzrd5mdhB2Efe
...
lzHutyBZunsJ+fP6kBQ73gjj3Nu/JiM=
-----END PRIVATE KEY-----
    • host.csr
-----BEGIN CERTIFICATE REQUEST-----
MIIErDCCApQCAQAwZzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRUwEwYDVQQH
...
D9mL7nZty7RtNHfMQvdupP8x6E9yeZB9Z227t+rkQoE0fUN1g6GaPdB2yFoIm510
-----END CERTIFICATE REQUEST-----
    • host.crt (valid for 500 days)
-----BEGIN CERTIFICATE-----
MIIFUTCCAzkCFGZE+l0Tx8RVS7z7JkHHu7ppjSZCMA0GCSqGSIb3DQEBCwUAMGMx
...
84DxImyoe554wsw6rxiFdyV/IX6b
-----END CERTIFICATE-----

 

6) Check if the Certificate matches the Private Key.

In some cases, you may be trying to use certificate files that have been generated by some other or old Private Keys.  This can happen during the certificate renewal or if there were multiple attempts to generate the certificate. Use the following openssl commands to generate MD5 checksum for your Private key and Certificate.

openssl x509 -noout -modulus -in fix.itbit.pem | openssl md5
MD5(stdin)= cbb4fb46fe8a7267332a41daf8ee8521
openssl rsa -noout -modulus -in fix.itbit.pem | openssl md5
MD5(stdin)= cbb4fb46fe8a7267332a41daf8ee8521

THe MD5 checksum values must match. If they do not match it's required either to update fix.itbit.pem with the correct files, or generate new files to update fix.itbit.pem. If new certificate files are generated, the new ca.crt file must be sent to Paxos and to update the server before you can test the connection with the new certificates.

The same file (fix.itbit.pem) is used as the input for this command since it contains both, the key and the certificate.

The same procedure can be used to verify if CA cert matches the CA key:

openssl rsa -noout -modulus -in ca.key | openssl md5
MD5(stdin)= 5f5585fd0e8a248c15a5c8612a42f589
openssl x509 -noout -modulus -in ca.crt | openssl md5
MD5(stdin)= 5f5585fd0e8a248c15a5c8612a42f589

 

7) Validate Stunnel configuration

If your FIX Client doesn't natively support TLS connection, a Stunnel proxy can be used. The FIX Client must be configured to connect to Stunnel. The Stunnel proxy will use the generated certificates to create and manage the TLS connection to the FIX server.

client = yes
foreground = yes
pid = /home/src/itbit.stunnel.pid
socket =l:TCP_NODELAY=1
socket =r:TCP_NODELAY=1

[itbit-sandbox]
client = yes
accept = 127.0.0.1:1234
cert = /{PATH-TO-CERT}/fix.itbit.pem
connect = sandbox-fix.itbit.com:1234
CAfile = /{PATH-TO-CERT}/itbit-ca.pem
verifyChain = no

Verify the following options:

  • cert - The path to fix.itbit.pem with host key and certificate.
  • connect - FIX server address and port provided to you during the onboarding.
  • CAfile - The path to itbit-ca.pem file with Paxos certificate copied from the onboarding page.

 

8) Updating the certificate

  1. The following situations may require the keys to be regenerated and sent to Paxos to update the keys on FIX Server (Paxos) side:
    • if the ca.key has been compromised;
    • if the ca.crt file is about to expire; 

      Here is the command to verify the expiration date for ca.crt:

      openssl x509 -noout -in ca.crt -enddate
  2. If only the host.key (or fix.itbit.pem) has been compromised or lost, or host.crt got expired: you can generate a new fix.itibit.pem and update it on the FIX Client. No need update the ca.crt on Paxos side. 
    • Execute the following commands from the onboarding procedure to generate a new fix.itbit.pem:
openssl genrsa -out host.key 4096
openssl req -new -key host.key -out host.csr
openssl x509 -req -in host.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out host.crt -days 500 -sha256
cat host.crt host.key > fix.itbit.pem
openssl verify -CAfile ca.crt fix.itbit.pem

 

 

 

Was this article helpful?
0 out of 0 found this helpful

Articles in this section