Introduction

Atheos Gateway, version 02.00.00 has been used successfully for almost 3 years now without any significant maintenance. The integration of High Security Modules (HSM) lead the development team to reengineer it heavily.

The version 03.00.00 is equivalent to the version 02.00.00 in regard to the Nexo functionalities.

The changes brought by the first release of version 3 are the basis for HSM integrations.

What’s new?

• New configuration file structure

• Many parameters have been added to the configuration file

• The configuration may reference environment variables

• Automatic creation of the files directory structure on the first startup

• A unique session identifier is added to the sequence number of every message

• The log file now contains more information and is more structured

• The private key of the server may be hosted by SoftHSM v2

New configuration file structure

The notion of sections has been introduced with version 3. The configuration file is no longer a simple list of key/value pairs but these key/value pairs are now organized into sections.

Many parameters have been added to the configuration file

Many new parameters have been added or renamed in the configuration file of version 3 to improve the customization of the behaviour of the Gateway.

The configuration file may reference environment variables

The configuration file may reference environment variables. The value of a parameter may be replaced with an environment variable. It provides another source for the value of a parameter.

Its name must be preceded with $$. Thus, $$DIRECTORY_NAME refers to the environment variable DIRECTORY_NAME.

Automatic creation of the files directory structure

Version 2 relied on an installation script to create its required directory structures. This installation script is no longer required. Atheos Gateway will create its directory structures if they do not exist.

A unique session identifier is added to the sequence number of every message

All messages exchanged between a POI and the Gateway are saved. The messages have a sequence number assigned to them related to the order they were received or sent.

Confusion could arise if more than one POI was configured at the same time all using the same POI ID. The sequence number format has been changed. It is still 8 characters long, but the first 6 characters makes a string unique to a session between the POI and the Gateway. The actual sequence number is now only 2 digits long.

The log file now contains more information and is more structured

The structure of the Gateway file has been improved. Also, more information is included such as the message type received from and sent to the POI.

The private key of the server may be hosted by SoftHSM v2

The Gateway uses a certificate to authenticate itself. It is possible to use the private key related to the certificate stored into SoftHSM (v2) as a first step in the HSM integrations.

Migration path from version 2 to version 3

The version 3 of the Gateway is not a drop-in replacement for version 2. The actions required to upgrade to this new version:

• Atheos Server must be updated to version xx.yy.zz

• Update the configuration file

• Update the configuration of the component ??????????????????????

Atheos Server must be updated to version xx.yy.zz

This is pretty straight forward. It should be handled the same way as the previous updates. The changes introduced to support version 3 of the Gateway are listed in the Atheos Server release notes.

Update the configuration file

The default configuration distributed with the Gateway version 3 contains many comments. This section contains general information that describes the overall configuration file. The sample configuration file is given at the end of this section.

NOTE: The content of the configuration is case-sensitive.

Currently, the sections defined in the configuration are:

• LogFile

• MessagesRepositories

• Connectivity

• ServerSSLCertificate

• ServerSSLPrivateKey

• Security Provider sections

• OpenSSL

• Performance

• Nexo

• PoiConfigurations

LogFile

The log file was defined in previous versions using only the parameter LogFile. It is now a section which contains the following parameters:

The URI parameter define the file that will be used for the log file. A fully qualified file name is required. It must comply to the following format: file://fully-qualified-filename. As an example, if the log file to be used is /var/log/amadis/atheosgw.log, the parameter should be:

URI = file:///var/log/amadis/atheosgw.log

Any missing directories in the log file path will be created with the permissions specified by the parameter DirectoriesPermissions. So, Atheos Gateway must have the rights to create the directories. If it is not the case, the directories must be created using another method.

The log file permissions will be set to the value of the parameter FilePermissions.

The permission values must be numerical. As an example, the permission rw-r--r shall be given as 0644. The leading zero is important which explicitly qualify an octal value.

MessagesRepositories

The exchanged messages between the POI and the Gateway are stored temporarily in a directory structure before being uploaded to the Atheos Server. The related parameters are:

The base directory is given by the parameter BaseDirectory. This parameter must be a fully qualified filename. As an example:

BaseDirectory = /home/amadis/files

Any missing directories in the path will be created with the permissions specified by the parameter DirectoriesPermissions. So, Atheos Gateway must have the rights to create the directories. If it is not the case, the directories must be created using another method.

The sub-structure required in this directory will be created and assigned the permissions given by DirectoriesPermissions.

The permissions of the files containing the messages will be set to the value of the parameter FilePermissions.

The permission values must be numerical. As an example, the permission rw-r--r shall be given as 0644. The leading zero is important which explicitly qualify an octal value.

Connectivity

The network connectivity parameters are specified in this section. They are:

The parameter ListeningPort is the port onto which the Gateway will listen for incoming connections.

The BindingAddress is the address onto which the Gateway will listen for incoming connections. Setting it to 0.0.0.0 will make the Gateway listen to any network interface on the server.

Parameters that are no longer in the configuration file

These parameters must be moved into the specific configuration files

MOVED

ASFileUploadSignatureKey

NexoMessagesUploadURL

GatewayId

DELETED

DebugDumpMessages

###############################################################################
#
# Atheos Gateway V3 Configuration File
#
# Copyright ©2005-2021 - 9164-4187 QUEBEC INC (“AMADIS”), All Rights Reserved
#
###############################################################################
#

[LogFile]

# Log file location.  A fully qualified file name must be supplied.
URI = file:///tmp/agw/var/log/amadis/atheosgw.log

# Directories permissions
DirectoriesPermissions = 0770

# File permissions
FilePermissions = 0640

[MessagesRepositories]

# Base directory where the messages received and sent to the POI are saved.
# Previously FileRepositoryBaseDir
BaseDirectory=/tmp/agw/home/amadis/files

# Directories permissions for the message repositories
DirectoriesPermissions = 0770

# File permissions for the message repositories
FilePermissions = 0640

[Connectivity]

# Server incoming connection port.  Previously ServerPort
ListeningPort = 55554

# Address on which the server will bind (listen) to.
BindingAddress = 0.0.0.0

# Server certificate used 
[ServerSSLCertificate]
CryptographicProvider = OpenSSL
Type = X509Certificate
Format = PEM
URI = file://server.crt

# Private key for the server certificate. Password protected keys are not
# supported yet.
[ServerSSLPrivateKey]
CryptographicProvider = OpenSSL
Type = PrivateKey
Format = PEM
URI=file://server.unprotected.key

#[ServerSSLPrivateKey]
#CryptographicProvider = hsm1
#Type = PrivateKey
#URI = pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=abe6ed66024f38b2;token=claude;id=%40%00;object=serverkey;type=private;pin-value=4321

[hsm1]

# Engine type (internal or HSM)
Type = PKCS11HSM

# Engine ID
ID=pkcs11

# Engine library path
SOPath=/usr/lib/x86_64-linux-gnu/engines-1.1/libpkcs11.so

# Engine module path as required by the engine shared object library.
ModulePath=/usr/lib/softhsm/libsofthsm2.so

# Engine PIN
PIN=4321

[OpenSSL]
Type = OpenSSL
Version = 1.0.0

[Performance]

# Maximum number of concurrent connections the server will handle before 
# queuing the other ones.
MaximumConnections = 10

# Pending connections queue length.  If MaximumConnections is reached, up to 
# PendingConnectionQueueLength connections will be queued before rejecting 
# them.
PendingConnectionQueueLength = 200

# Maximium wait time while listening for a new connection in microseconds.
ListeningMaximumWaitTime = 100000

# Time in seconds the server will wait before terminating
# active connections.
ShutdownDelay = 60

# Timeout in seconds of a connection with a POI.
SSLTimeout = 60

# Maximum wait time when waiting for an event on a socket.
SocketSelectMaximumWaitTime = 100000

# Nexo message initial input buffer size in bytes. This value shall not be
# lower than 2000 bytes.
NexoMessageInitialBufferSize = 48000

# Nexo Builder Buffer size in bytes. NexoBuilderErrorMessagesBufferSize bytes
# are reverved as the error message buffer.
NexoBuilderBufferSize = 48000

# How much space to reserve in the Nexo Builder Buffer for error messages.
# It must be lower than 3072.
NexoBuilderErrorMessagesBufferSize = 1024

[Nexo]
# Nexo protocol version included in the Nexo messages
ProtocolVersion = 6.0

# Terminal Manager Id included in the Nexo messages
TerminalManagerId=ATHEOS-TMS01

[PoiConfigurations]

# Base directory root where the configuration files and
# the management plans for the POIs are located.
BaseDirectory = /tmp/agw/home/amadis/poi

# Directories permissions for the message repositories
DirectoriesPermissions = 0770






# User under which the AtheosGW will be running.  Should not be root.
User=amadis

# Group under which the AtheosGW will be running.  Should not be root.
Group=amadis

#### File containing the server SSL certificate.
###ServerCertificateFile=/etc/amadis/server03.crt

#### File containing the server SSL key.  The key shall
#### not be password protected.  Its protection must be
#### done using the operating system build in security.
###ServerPrivateKey=/etc/amadis/server.unprotected.key

old file

# User under which the AtheosGW will be running.  Should not be root.
User=amadis

# Group under which the AtheosGW will be running.  Should not be root.
Group=amadis

# Maximum number of connections the server will handle before queuing 
# the other ones.
MaxConnections=10

# Incoming connection polling period in microseconds.
ListenPollingPeriod=100000

# Time in seconds the server will wait before terminating
# active connections.
ShutdownDelay=60

# File containing the server SSL certificate.
ServerCertificateFile=/etc/amadis/server03.crt

# File containing the server SSL key.  The key shall
# not be password protected.  Its protection must be
# done using the operating system build in security.
ServerPrivateKey=/etc/amadis/server.unprotected.key

# Timeout in seconds of a connection with a POI.
SSLTimeout=60000

# Polling period of the read function while waiting
# for some data from a POI.
SSLReadWaitTimeSec=0
SSLReadWaitTimeuSec=100000

# Base directory root where the configuration files  and
# management plans for the POIs are located.
POIDataRoot=/home/amadis/poi

# Version of the Nexo TMS protocol handled by the server.
# This value is included in the Nexo messges sent to the
# POIs.  Currently, it has no effect of the behavior of
# the server.
NexoTMSProtocolVersion=6.0

# Terminal Manager Id.  This value is include in Nexo 
# messages sent to the POIs.
TerminalManagerId=ATHEOS-NPS-TMS1

# Pending connections queue length.
# If MaxConnections is reached, up to PendingConnectionQueueLength
# connections will be queued before rejecting them.
PendingConnectionQueueLength=200