HOME | FIX GATEWAY DOCUMENT | DEMO | BUY NOW

	FixGateway and Fix Gateway Integration Kit (c) 2000-2006 Octatec Ltd

The SSL Integration kit allows you to add SSL security and encryption to Octatec's FixGateway FIX ENGINE, allowing the gateway to connect through 3rd party SSL products. It comes with an implementation using the OpenSSL library. NOTE: this software requires version 1 release 12 or higher of the FixGateway.

Introduction
OpenSSL Implementation
How does the integration kit work
Creating your own Implementation
Appendix I: Trying out the demo

Keywords: SSL, Secure Sockets, Encryption, Security, Fix Protocol, Fix Engine, Fix Gateway, Fix API, Financial Information Exchange, Windows

Summary: The Fix Gateway /SSL integration kit adds Secure Socket functionality the Fix Gateway FIX Engine

Introduction

What is the SSL Integration Kit?

This enables the Fix Gateway to create FIX sessions over an SSL Secure Socket. It does this by allowing you to integrate 3rd party SSL implementations with the FixGateway

Do I need to purchase a 3rd party product to get SSL functionality?

No. The SSL integration kit comes with an implementation that uses the free OpenSSL secure socket library, so you get SSL functionality ‘out-of-the-box’. If however, you already have a 3rd party SSL product, you should find no difficulty in integrating that product with the FixGateway using this kit.

Will the Integration Kit allow any 3rd party SSL product to work with FixGateway?

In principal, yes. However if you don't use OpenSSL, you will have to write the integration code yourself. The only requirement is, that the 3rd party product should be implemented over standard sockets, and that you should be able to obtain the underlying socket and use that in a select() call

OpenSSL Implementation

The SSL Integration Kit comes with a standard implementation based on the OpenSSL library. The source code of this implementation is included in the kit. The source code of OpenSSL is not included (that is freely downloadable here), but OpenSSL DLLs LIBs and headers are included, together with the openssl.exe program (used for creating keys).

The directory Octatec\fixgwSSL\1.00\OpenSSL contains the OpenSSL headers and C:\Program Files\Octatec\fixgwSSL\1.00\OpenSSL\lib contains the DLLs and LIB files. The source code for the OpenSSL based implementation object (FgwSslObject.FgwSSL.1) is located in C:\Program Files\Octatec\fixgwSSL\1.00\FgwSslObject.The most important class in the implementation is FgwSslImpl in FgwSslImpl.cpp.It is this class that actually does the work. If you want to extend the functionality you can derive your own object from this one - in particular, you can override two methods...

virtual bool ValidateServerCert(X509 *server_cert, char *subject, char* issuer); and
virtual bool ValidateClientCert(X509 *client_cert, char *subject, char* issuer);

...in order to provide specific certificate and key validations specific to your requirements.

The actual COM object is implemented by the class CFgwSSL in FgwSSL.h. This object simply delegates to the implementation object, FgwSslImpl.

NB: If you try and build the COM object and get errors, make sure you are not trying to build a UNICODE configuration!

Using The SSL Object

The object is already registered by the installation. There are 2 config files in Octatec\fixgwSSL\1.00\demo_configs. These 2 files can be used to replace the config files for the test applications fixgwsrvr and fixtest that come with the standard FixGateway application. If you do this, make sure you copy the certificate and key (.pem) files to an accessible location, e.g. create a directory called ssl under the FixGateway installation directory (Octatec\fixgw\1.00) and copy the test certificates from the fixgwSSL\TestCertificates directory to ssl. The directory Octatec\fixgwSSL\1.00\TestCertificatescontains test certificates and the openssl.exe program that can be used to generate more certificates and keys.

The FixGateway config file should have entries like...

SocketObject FgwSslObject.FgwSSL.1
SSLkey        %\ssl\server.pem
SSLcert       %\ssl\server.pem
SSLparam      s

The SSLparam parameter is an 'option string', the following options are available...

s - server mode
c - client mode
x - a certificate is required from the peer (with this option, if the peer does not supply a certificate, it is considered an error)

NB: it is very important to get the s and c parameters correct. If you are running as a server you must use s, otherwise c. You can decide whether to use x depending on the level of security you want.

This object creates logfiles named fgwssl_c.log orfgwssl_s.log (for client and server modes) in the system temp directory, you can restrict these files to errors only by rebuilding with _VERBOSE_ not defined in log.h

More About OpenSSL

A quote from the OpenSSL home page…

"OpenSSL is based on the excellent SSLeay library developed by Eric A. Young and Tim J. Hudson. The OpenSSL toolkit is licensed under an Apache-style licence, which basically means that you are free to get and use it for commercial and non-commercial purposes subject to some simple license conditions

This software package uses strong cryptography, so even if it is created, maintained and distributed from liberal countries in Europe (where it is legal to do this), it falls under certain export/import and/or use restrictions in some other parts of the world.
PLEASE REMEMBER THAT EXPORT/IMPORT AND/OR USE OF STRONG CRYPTOGRAPHY SOFTWARE, PROVIDING CRYPTOGRAPHY HOOKS OR EVEN JUST COMMUNICATING TECHNICAL DETAILS ABOUT CRYPTOGRAPHY SOFTWARE IS ILLEGAL IN SOME PARTS OF THE WORLD. SO, WHEN YOU IMPORT THIS PACKAGE TO YOUR COUNTRY, RE-DISTRIBUTE IT FROM THERE OR EVEN JUST EMAIL TECHNICAL SUGGESTIONS OR EVEN SOURCE PATCHES TO THE AUTHOR OR OTHER PEOPLE YOU ARE STRONGLY ADVISED TO PAY CLOSE ATTENTION TO ANY EXPORT/IMPORT AND/OR USE LAWS WHICH APPLY TO YOU. THE AUTHORS OF OPENSSL ARE NOT LIABLE FOR ANY VIOLATIONS YOU MAKE HERE. SO BE CAREFUL, IT IS YOUR RESPONSIBILITY.

CREDIT INFORMATION: This product includes cryptographic software written by Eric A. Young (eay@cryptsoft.com). This product includes software written by Tim J. Hudson (tjh@cryptsoft.com)."

And a quote from the OpenSSL Installation README...

"The OpenSSL toolkit includes:

libssl.a:
Implementation of SSLv2, SSLv3, TLSv1 and the required code to support
both SSLv2, SSLv3 and TLSv1 in the one server and client.

libcrypto.a:
General encryption and X.509 v1/v3 stuff needed by SSL/TLS but not
actually logically part of it. It includes routines for the following:

     Ciphers
        libdes - EAY's libdes DES encryption package which has been floating
                 around the net for a few years. It includes 15
                 'modes/variations' of DES (1, 2 and 3 key versions of ecb,
                 cbc, cfb and ofb; pcbc and a more general form of cfb and
                 ofb) including desx in cbc mode, a fast crypt(3), and
                 routines to read passwords from the keyboard.
        RC4 encryption,
        RC2 encryption      - 4 different modes, ecb, cbc, cfb and ofb.
        Blowfish encryption - 4 different modes, ecb, cbc, cfb and ofb.
        IDEA encryption     - 4 different modes, ecb, cbc, cfb and ofb.

     Digests
        MD5 and MD2 message digest algorithms, fast implementations,
        SHA (SHA-0) and SHA-1 message digest algorithms,
        MDC2 message digest. A DES based hash that is popular on smart cards.

     Public Key
        RSA encryption/decryption/generation.
            There is no limit on the number of bits.
        DSA encryption/decryption/generation.
            There is no limit on the number of bits.
        Diffie-Hellman key-exchange/key generation.
            There is no limit on the number of bits.

     X.509v3 certificates
        X509 encoding/decoding into/from binary ASN1 and a PEM
             based ascii-binary encoding which supports encryption with a
             private key. Program to generate RSA and DSA certificate
             requests and to generate RSA and DSA certificates.

     Systems
        The normal digital envelope routines and base64 encoding. Higher
        level access to ciphers and digests by name. New ciphers can be
        loaded at run time. The BIO io system which is a simple non-blocking
        IO abstraction. Current methods supported are file descriptors,
        sockets, socket accept, socket connect, memory buffer, buffering, SSL
        client/server, file pointer, encryption, digest, non-blocking testing
        and null.

     Data structures
        A dynamically growing hashing system
        A simple stack.
        A Configuration loader that uses a format similar to MS .ini files.

openssl:
     A command line tool that can be used for:
        Creation of RSA, DH and DSA key parameters
        Creation of X.509 certificates, CSRs and CRLs
        Calculation of Message Digests
        Encryption and Decryption with Ciphers
        SSL/TLS Client and Server Tests
        Handling of S/MIME signed or encrypted mail

PATENTS

Various companies hold various patents for various algorithms in various locations around the world. YOU are responsible for ensuring that your use of any algorithms is legal by checking if there are any patents in your country. The file contains some of the patents that we know about or are rumoured to exist. This is not a definitive list.

RSA Security holds software patents on the RC5 algorithm. If you intend to use this cipher, you must contact RSA Security for licensing conditions. Their web page is http://www.rsasecurity.com/.

RC4 is a trademark of RSA Security, so use of this label should perhaps only be used with RSA Security's permission.

The IDEA algorithm is patented by Ascom in Austria, France, Germany, Italy, Japan, Netherlands, Spain, Sweden, Switzerland, UK and the USA. They should be contacted if that algorithm is to be used, their web page is http://www.ascom.ch/."

In the above README, the libraries referred to are renamed libeay32.dll/libeay32.lib and SSLeay32.dll/SSLeay32.lib

OpenSSL Links...

http://www.openssl.org/support/faq.html (Open SSL FAQ)

http://www.openssl.org/source/ (OpenSSL source code download)

http://www.openssl.org/docs/ (OpenSSL documentation)

Certificates

The directory Octatec\fixgwSSL\1.00\TestCertificatescontains some test certificates and the openssl.exe program (together with CA.pl and CA.sh - for documentation purposes only) These items make up only a small fraction of the total OpenSSL Certificate resources available in the OpenSSL download, if you need more you should download the whole of OpenSSL.

Here are some Certificate specific links...

http://www.octaldream.com/~scottm/talks/ssl/opensslca.html (Creating Certificates, general description)

http://www.cs.indiana.edu/~chiuk/security/ssl/openssl/certificates/ (Creating Certificates, command list)

http://www.post1.com/home/ngps/m2/howto.ca.html (Creating Certificates - a useful howto)

http://www.pseudonym.org/ssl/ssl_server_certs.html (Creating Certificates: alternative description)

How does the integration kit work?

In order to use a 3rd Party's Secure Socket product, one important criterion must be bet. The Socket Descriptor that the 3rd part returns must be a valid WINSOCK2 SOCKET, i.e. it must be usable in the standard select() call, and work correctly when other WINSOCK2 SOCKETS are present in the select() call. (or if the 3rd party uses some other descriptor, it must be possible to access an underlying SOCKET that can be used in a select() call)

The following entries in the FixGateway config file are used…

SocketObject ObjectName # the name of the COM Object that implements IFgwSocket
SSLkey        "any string" # probably the name of key-file
SSLcert       "any string" # probably the name of certificate-file
SSLparam      "any string" # probably an 'options string' or additional config file

Under the OpenSSL implementation supplied with the kit, these entries look like...

SocketObject FgwSslObject.FgwSSL.1
SSLkey        %\ssl\server.pem
SSLcert       %\ssl\server.pem
SSLparam      s

FixGateway support for the 3rd Party Socket API is via an in-process COM object. FixGateway can't know all possible APIs that might exists, so it defines a standard API in the form of a COM Interface, IFgwSocket, which must be implemented using a 3rd party suppliers own API. This object is identified by the SocketObject parameter in the config file. C++ is probably the best way of implementing this interface. Once written, this interface is used transparently by the Fix Gateway process. As already mentioned, an implementation of this object using OpenSSL is supplied with the Integration Kit.

The IFgwSocket interface matches the standard socket api calls exactly and is used internally by the FixGateway in exactly the normal way. Any 3rd party API should provide samples of how to integrate it with the normal socket server call sequence

socket()
bind()
listen()
accept()
select()
recv()
send()

and the normal socket client call sequence

socket()
connect()

Because the IFgwSocket interface is basically the same as the standard socket api, it should make implementation easy.

The IFgwSocket Interface

[id(01)] HRESULT socket(long af, long type, long proto, [out,retval]long *sock);
[id(02)] HRESULT recv(long sock, unsigned char *buff, long len, long flags, [out,retval]long *result);
[id(03)] HRESULT send(long sock, unsigned char *buff, long len, long flags, [out,retval]long *result);
[id(04)] HRESULT connect(long sock, unsigned char *name, long namelen, [out,retval]long *result);
[id(05)] HRESULT bind(long sock, unsigned char *name, long namelen, [out,retval]long *result);
[id(06)] HRESULT listen(long sock, long backlog, [out,retval]long *result);
[id(07)] HRESULT accept(long sock, unsigned char *addr, long *addrlen, [out,retval]long *result);
[id(08)] HRESULT Init(unsigned char* SSLkey, unsigned char* SSLcert, unsigned char* SSLparam
[out,retval]long *result);
[id(09)] HRESULT closesocket(long sock, [out,retval]long *result);
[id(10)] HRESULT shutdown(long sock, long how, [out,retval]long *result);
[id(11)] HRESULT getsockname(long sock, unsigned char *name, long *namelen, [out,retval]long * result);
[id(12)] HRESULT setsockopt(long sock, long level, long name, unsigned char *val, long len, [out,retval]long *result);

When implementing this interface, it is important that use the same IDs, and have all the methods in the same order! If you implement your own object, the best idea is to modify the trivial implementation supplied with the installation.

The only method that doesn't have a direct equivalent in the standard SOCKET api is Init(). This method is called immediately after the object is created, the parameters are the values taken from the config file. This method can be used for any initialization required by the 3rd part API, the 3 parameters can be anything that is appropriate, they need not all be specified, in which NULLs will be used. The return value of Init() is 1 for success, 0 for failure.

Creating Your Own Implementations

The integration kit comes with a full Implementation of IFgwSocket using OpenSSL (FgwSslObject.FgwSSL.1). You can use this as a guide. It also comes with a Trivial implementation of IFgwSocket (FixGW.Socket.1) that merely passes calls to the native socket API, this is also a good starting point for your own implementation. To further help with this, there is a test program (supplied in source form) to test objects that implement IFgwSocket.

If you want to create your own implementation, the best thing to do is modify the trivial implementation found in C:\Program Files\Octatec\fixgwSSL\1.00\FgwSockObject.The actual work is done in the implementation object FgwSockImpl found in FgwSockImpl.h, and this is probably all you will need to alter.

The test program is located in C:\Program Files\Octatec\fixgwSSL\1.00\FgwSockTest, it has menu options to Start a Server and Start a Client, they will then exchange a small amount of data (i.e. run the test program and take File/Server Test, then start a new instance of the program and take File/Client Test). All functionality is located on the File menu. NOTE: to test this trivial object switch off SSLmode form the File menu, is SSL mode is on, the SSL object referred to above is tested.

NB: If you try and build the trivial implementation and get errors, make sure you are not trying to build a UNICODE configuration!

Appendix I Trying out the demo

The FixGateway comes with demo config files. This kit comes with replacements for those files so that the FixGateway demo programs uses the SSL object supplied with this kit.

Assuming the FixGateway is installed in D:\Program Files\Octatec\fixgw\1.00\ and the SSL kit is installed in D:\Program Files\Octatec\fixgwSSL\1.00 …

copy
D:\Program Files\Octatec\fixgwSSL\1.00\demo_configs\*.cfg ->
D:\Program Files\Octatec\fixgw\1.00\configs

create folder
D:\Program Files\Octatec\fixgw\1.00\SSL

copy
D:\Program Files\Octatec\fixgwSSL\1.00\TestCertificates\server.pem ->
D:\Program Files\Octatec\fixgw\1.00\SSL

And that's it, now just run the FixGateway demo programs, and they'll automatically use SSL