Log files

A file system is used to log messages for FIX Antenna recovery.

Log files are created in the directory specified in configuration parameters (the "LogDirectory" property).

Files with the *.conf extension (configuration files) contain basic session information.

IncomingSeqNum MsgSeqNum of the last incoming message that was successfully processed
Acceptor or Initiator role
Sender SenderCompID
Target TargetCompID
CorrectlyTerminated 'true' if the session was terminated correctly, otherwise - 'false'
FIX protocol version

Incoming messages are stored in files with the .in extension.

Outgoing messages are stored in files with the .out extension.

Files related to the same session have the same base part of the name (the part before a dot)

The engine.log file, storing information about FE operation is also created in the log directory.

Log files are used during automatic session reestablishment. Thus, to ensure a "clean" run of FIX Antenna, it is necessary to remove all the files from the log directory (the "LogDirectory" property).

Encryption

The exchange of sensitive data across public networks may require the usage of data encryption techniques to mask the FIX application-level messages. This chapter describes issues related to data encryption in FIX Antenna C.

In order to operate in secure mode FIX Antenna C requires GNU Privacy Guard command-line utility (GnuPG). It can be downloaded from http://www.gnupg.org. Please follow the OS-specific installation instructions included into GNU Privacy Guard distribution when installing. On finishing the installation, a PATH environment variable must be adjusted to include the directory containing Gnu PG command-line utility (gpg.exe on Windows).

Supported algorithms

Supported FIX protocol encryption methods

The following FIX protocol encryption methods are supported:

PGP/DES-MD5 ( EncryptMethod(98) = 5 )

Supported PGP public-key algorithms

The following PGP public-key algorithms are supported:

RSA
DSA
ElGamal

The allowed key size for DSA and ElGamal algorithms is 768 up to 4096 bits. The highest recommended key size is 2048 bits.

Supported DES modes of operation

FIX Antenna C operates in DES Cipher Block Chaining Mode (CBC) only. Applying other DES modes at the counterparty's side such as Electronic Codebook Mode (ECB), Cipher Feedback Mode (CFB) leads to premature session termination.

Key management

FIX Antenna C library does not have its own keyring storage and uses GnuPG keyring storages instead.

Establishing a secure FIX session requires at least two PGP keys to be present in GnuPG keyring storages. These are:

Public encryption key of the recipient (identified by TargetCompID (56) ). This encryption key is necessary for secure establishment of DES session key. The key must be trusted.
Private signing key of the sender (identified by SenderCompID (49) ). This signing key is necessary for authenticating the originator to the recipient and must be trusted.

A secure password is required to access the private key. FIX Antenna C looks for this password in the file identified by EncryptionConfigFile configuration property.

Establishing secure session

All session-level details of FIX encryption are encapsulated inside the FIX Engine (FE).

Encryption Config File

Below you can see the alphabetically sorted list of all encryption parameters with references to their documentation:

ChanBindingMustBeChecked
PGP.key.*

The following parameters can be assigned in the encryption configuration file:

# If "true" the channel binding information will be checked 
# the default value is "true"
ChanBindingMustBeChecked = true
# Passwords for PGP private keys 
PGP.key.SENDERCOMPID = PASSWORD

Compatible OpenPGP software and SDKs

The following software was tested for compatibility with FIX Antenna C:

Gnu Privacy Guard
OpenPGP
Cryptix OpenPGP 20030801 and later snapshots

In fact, any software supporting OpenPGP message format (see RFC2440) is compatible with FIX Antenna C. Please refer to GNU Privacy Guard COMPATIBILITY ISSUES for details.

SSL

FIX Antenna does not provide an SLL layer as internal implementation. Instead the user may choose the desired proven SSL implementation because FIX Antenna can work over any SSL layer provided by the 3rd party. The recommended practice is to use stunnel software (www.stunnel.org) using the "Forwarding an insecure port securely from one machine to another" mechanism.

Let us say you want to establish a FIX session (according to the FIX protocol)from local machine to a remote machine, but do not have an SSL aware FIX-client. You can have your machine talk to stunnel on the local machine, which then encrypts the packets and sends them to another stunnel running on the remote machine, which forwards them in clear text to the FIX server on that machine.

Example: Assume that the FIX Engine is listening to the port 9106. You must have some port on the remote machine that listens to the encrypted connection. You can pick some arbitrary high port (for cases in which you are not running as root this may be the only option, for example). So, we could pick the port 8888.

So we need the following:

foo - the local FIX Engine. Stunnel listens on foo:9106, forwards to bar:8888
bar - the remote FIX Engine. Stunnel listens on bar:8888, forwards to bar:9106.

Now we have to perform the following steps:

run on foo: stunnel -c -d 9106 -r bar:8888
run on bar: stunnel -p /path/to/stunnel.pem -d 8888 -r bar:9106

Error handling

If errors occur, FIX Antenna C API functions return B2BITS_FALSE. To get an error cause report, use the B2BITS_GetLastErrorDescription() function.

For example:

if( B2BITS_TRUE != B2BITS_FixEngine_Init("",-1,"","") )
{
    printf( "Error: %s\n", B2BITS_GetLastErrorDescription() );
    return 1;
}

FAQ

Is it possible to create more than one instance of FIX Antenna C?

Yes, it is possible to create many instances of FIX Antenna C as soon as they use different listening ports.

Is it possible to create more than one instance of FIX Antenna C using the same logging directory?

Yes. However it is recommended to set a different logging file. Otherwise different instances will put logging data to the same file and it will be difficult to distinguish records written by different instances.

May I put session log files to the log directory and expect that FIX Antenna C will analyse them when a new session with the same parameters is created?

Yes. FIX Antenna C loads all session information on session creation time.

FIX Antenna C was incorrectly terminated. I don't want the session to be restored on next start. What should I do for a clean start?

Clean the logging directory before creating a new instance of FIX Antenna C.

How can I do the customization (add user-defined fields, messages or change field and message definitions)?

User Defined Fields (the tag numbers 5000 to 9999) are handled like ordinary fields. User-defined FIX messages (e.g. U1, U2) are also handled like ordinary messages. To do the customization, please see the description of the Validation.AdditionalFields configuration property.

How to fix the "Repeating group fields out of order"error?

Example: 8=FIX.4.3 | 9=285 | 35=X | 49=FIXERBRIDGETRD1 | 34=1 | 57=B2BTEST1 | 52=99990909-17:17:17 | 268=4 | 269=2 | 270=9539.500000 | 271=1 | 272=20041208 | 273=13:34:10.000 | 290=1 | 269=4 | 27 0 =9539.500000 | 271=4294967295 | 272=20041208 | 273=13:34:10.000 | 290=1 | 269=Z | 270=9528.000000 | 271=401 | 290=1 | 269=Y | 270=0.000000 | 271=0 | 290=1 | 10=019 | [ERROR] Repeating group fields out of order [RefSeqNum: 1, RefTagID: 269, RefMsgType: X]

Solution: The reason of this problem cannot be detected easily. The required fields of both FIX message itself and (AdditionalFields) group must be filled out with corresponding values and any gap or change in tag order leads to an error (it is true for both standard and custom messages). Therefore, both standard and additional group fields must be checked for validity and then processed again. Extra attention must be paid to the order of fields in the repeating FIX group. For this particular example: tag 290 is placed before tag 269 (wrong tag order).Place the 290 tag and its value after the tag 269 and process the message again to solve the problem.

How to remove a group from Repeating Groups?

Use the FIXGroup.remove(int tag) method, where tag is a Repeating Group Leading Tag.

Is it possible to send messages in onLogonEvent handler?

When session-acceptor receives a Logon message, the onLogonEvent is fired. Sending messages in this event handler causes session none graceful termination. The reason is that the FIX protocol requires the first message to be Logon. It is prohibited to send messages in onLogonEvent handler.

How to extend FIX message with repeating group defined in FIX protocol?

The AdditionalFields mechanism requires repeating the group specification fully. It is not enough to add a repeating group leading tag to add this group to the FIX message - all tags of this group have to be enumerated as well. For example the correct extension of the BF message is: Validation.AdditionalFields = FIX44:BF:386(336,625?)

Is it possible to use B2BITS_FixMessage and B2BITS_FixGroup after B2BITS_FixEngine_Destroy() call?

It is prohibited to continue using B2BITS_FIXMessage and B2BITS_FixGroup objects after FixEngine_Destroy() call, you may only destroy them.

Troubleshooting

I get "ERROR: Error: License is not valid - components will be stopped! Please contact us at sales@btobits.com for further assistance." error message right after start.

This error means that you have some problem with license file. Possible cases:

License is expired
License is invalid
License cannot be found

Make sure that your engine.license file is located according to the value of 'LicenseFile' property. Try to set the full path to engine.license in the 'LicenseFile' property. Send your logs and license file to sales.nosp@m.@bto.nosp@m.bits..nosp@m.com.

FIX Antenna cannot create listen port on start

Make sure that this port is not in use by some other application. Try

netstat -a

to get a list of used ports.