External Components

Installation of External Components¶

External Components

Java Development Kit (JDK)
Hardware Security Module
Application Server
Oracle Database
Two-Factor Authentication Devices

Java Development Kit (JDK)¶

JDK can be freely downloaded from Sun Microsystems at http://java.sun.com/. JDK must be installed with the default settings. Follow the on screen installation instructions for the JDK to complete the installation.

ActiveAccess and ActiveAccess+RuPay require the installation of Oracle JDK 1.8 or OpenJDK 1.8. It is generally advisable that you install the latest minor version within a supported JVM.

You must only use one of the specified JVM versions. This is referred to as a compatible JDK in this document. Note that a newer version of JVM may not necessarily be backward compatible.

Hardware Security Module¶

ActiveAccess supports PKCS #11 Cryptographic API. For installation of the HSM module, please refer to your HSM manual.

Note

For testing purposes, you can use the Sun JCE provider, available during setup.

Installing the HSM module

The path of the PKCS #11 library file will need to be specified during ActiveAcces installation.
The slot number must be selected during ActiveAccess installation.
The PIN created during the installation of your HSM will be required during ActiveAccess installation.

Thales e-Security HSM

If you are using a Thales e-Security nShield HSM, the environment variable CKNFAST_OVERRIDE_SECURITY_ASSURANCES is required to be set for key generation.

Linux¶

Edit the startup file (~/.bashrc)
Add the following to the end of the file:
export CKNFAST_OVERRIDE_SECURITY_ASSURANCES=all
Save and close the file.
Load the startup file using the following:
\$ source ./profile
Verify that the variable is set by executing the following:
echo \$CKNFAST_OVERRIDE_SECURITY_ASSURANCES
The output should be all.

Windows¶

In your system's Control Panel\System and Security\System, click on Advanced system settings link.
Click Environment Variables….
In the System variables section, create a new environment variable:
Variable name: CKNFAST_OVERRIDE_SECURITY_ASSURANCES
Variable value: all
To verify if the variable has been set, open a new Command Prompt window, and execute the following:
echo %CKNFAST_OVERRIDE_SECURITY_ASSURANCES%
The output should be all.

Application Server¶

ActiveAccess supports Java Application Servers compatible with Servlet specification 3.0. Install your preferred compatible application server with default settings. Please follow the installation instructions from the application server's documentation.

Tomcat

Tomcat is freely available for download from Apache at http://tomcat.apache.org/.

Install Tomcat with default settings. Please follow Tomcat installation instructions from the Tomcat documentation.
Tomcat HTTP server starts on port 8080 by default. In order to change the port settings edit Tomcat/conf/server.xml

Update the following section in the configuration for this port number:

<!-- ==================== Connectors ==================== -->

<!-- Normal HTTP Connector -->

<Connector executor="tomcatThreadPool"

port="8080" protocol="HTTP/1.1"

connectionTimeout="20000"

redirectPort="8443" />

Configuring SSL¶

ActiveAccess requires that communication between client and server uses HTTPS. Configure the application server to run in HTTPS mode.

Tomcat SSL Configuration

To configure Tomcat running in HTTPS mode, please refer to the following:

For Tomcat 8.0+: https://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html

For Tomcat 8.5+: https://tomcat.apache.org/tomcat-8.5-doc/ssl-howto.html

Please note Tomcat supports two modes of SSL Connectors: JSSE and APR, for which the configuration is different; please refer to the relevant configuration sections in the above Tomcat documentation, for details.

An example configuration for JSSE SSL configuration taken from the Tomcat 8.0 documentation is provided below:

Create KeyStore (using Java Keytool):

To create a new Java KeyStore from scratch, containing a single self-signed Certificate, execute the following from a terminal command line:

Windows¶

"%JAVA_HOME%\bin\keytool" -genkey -alias appserver -keyalg RSA

Unix¶

\$JAVA_HOME/bin/keytool -genkey -alias appserver -keyalg RSA

(The RSA algorithm should be preferred as a secure algorithm, and this also ensures general compatibility with other servers and components.)

This command will create a new file, in the home directory of the user under which you run it, named ".keystore". To specify a different location or filename, add the -keystore parameter, followed by the complete pathname to your KeyStore file, to the keytool command shown above. For example:

Windows¶

"%JAVA_HOME%\bin\keytool" -genkey -alias appserver -keyalg RSA

\-keystore \path\to\my\keystore

Unix¶

\$JAVA_HOME/bin/keytool -genkey -alias appserver -keyalg RSA

\-keystore /path/to/my/keystore

You will also need to reflect this new location in the application server's configurations, for example, server.xml configuration file for Tomcat:

Example

Configure the Tomcat connector (in the file TOMCAT_HOME/conf/server.xml)

<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->

<Connector

protocol="org.apache.coyote.http11.Http11NioProtocol"

port="8443" maxThreads="200"

scheme="https" secure="true" SSLEnabled="true"

keystoreFile="${user.home}/.keystore" keystorePass="changeit"

clientAuth="false" sslProtocol="TLS"/>

Bypassing the HSM Password Dialog Box

ActiveAccess displays a dialog box for HSM password entry, when you start Tomcat.

In order to suppress the dialog box and enter the password in the console, add the following parameter to JAVA_OPTS in the catalina.sh file of Tomcat:

\-Dconsole

Or alternatively, you can directly bypass the HSM password by adding the following line in activeaccess.properties configuration file (located in the AA_HOME directory created during installation):
HSM_PASSWORD= < password >
Replace < password > with the base64 encoded format of your HSM password.
Base64 encoding
For base64 encoding, the following command can be used in Ubuntu Linux to generate a base64 encoded string with default settings:
```
 echo -n 'YourPlainTextPassword' | base64
```
The output of the command above will be:
```
WW91clBsYWluVGV4dFBhc3N3b3Jk
```

Increasing the Java Heap Size

JRE allocates 64MB of heap memory to a Java process by default. It is quite often necessary to increase this rather conservative memory allocation for server applications.

Tomcat

To increase the heap size available to Tomcat add the following line to catalina.bat (Windows) or catalina.sh (UNIX):

set JAVA_OPTS= -Xms<min_heap> -Xmx<max_heap>

For example in order to set the minimum heap size to 256MB and allow the heap to grow up to 512MB use:

set JAVA_OPTS= -Xms256m –Xmx512m

Oracle Database¶

Character Set

The database character set must be AL32UTF8 to support all Unicode characters.

User Name and Password for a database

This is the user name and password that you use to access the database. You may set these database user names to the same user (schema) that you have specified for the database owner (The schema that holds all ActiveAccess database objects). However, if you wish to reserve the database owner for administration purposes and set up a more restricted user for ActiveAccess to access the database schema, please the grant the following permissions to the restricted database user:

These permissions require confirmation:

Objects: EXECUTE

PL/SQL: EXECUTE

Sequences: ALTER, SELECT

Tables: DELETE, INDEX, INSERT, REFERENCES, SELECT, UPDATE

Note

Please refer to your database server documentation for the installation and configuration of Oracle server.

Configuring DCD (Dead Connection Detection)

Set the optional parameter SQLNET.EXPIRE_TIME to 10 (for 10 minutes) in the sqlnet.ora configuration file.

The configuration file is normally located at $ORACLE_HOME/network/admin directory.

The value of this parameter determines how often SQL*NET attempts to verify that the connection is still alive. This is to prevent shadow connections to be left open indefinitely.

There are a number of processes that hold a permanent or temporary lock on the database. If the connection to database is abruptly terminated (network disconnected or the server is turned off), the lock remains and will not be reclaimed by other competing processes. This affects sending notification messages via email, scheduling card upload and user upload jobs or registration services.

Configuring DCD ensures that this situation is automatically rectified after the specified time out.

Connection Pooling and Firewall¶

This section provides important operational information for proper configuration of the environment, when the database server is behind a firewall.

ActiveAccess components use a technique known as connection pooling to improve the performance of database related tasks. Connection pooling improves performance by reusing previously established connections. However, this may cause a problem when the database server is behind a firewall. The usual symptom is that the application appears to become unresponsive or frozen after a long period of inactivity.

This is due to firewall idle connection time-out setting. A firewall typically drops idle connections after a configurable time-out has expired. This causes further data transmission through these connections to be ignored by the firewall. Since most firewalls simply ignore the data packets and do not respond, this leaves the sender in a state of wait. The length of this wait state depends on the operating system's time-out setting. For Windows this is typically 15 seconds while the default Solaris time-out is 8 minutes during which the application appears to be frozen.

To prevent this problem ActiveAccess and ActiveIssuer components close idle database connections after 15 minutes. Make sure that your firewall time out setting is at least 1 minute longer than the default application idle connection time out.

The default can be changed by setting the DB_IDLE_TIMEOUT configuration option (in seconds) for each component.

Find Transactions Performance¶

The performance of transaction search can be greatly improved by analysing the HISTORYSESSIONS table on a regular basis.

Run the following SQL commands on the database monthly:
analyze table HISTORYSESSIONS compute statistics;
analyze table AUTHSESSION compute statistics;
analyze table CARD compute statistics for all indexed columns;
analyze table CARDDATA compute statistics for all indexed columns;
analyze table REQUEST compute statistics for all indexed columns;

Analysing a table can take a long time and puts extra load on the database. Analyse the tables at a time when database activity is low.

Two-Factor Authentication Devices¶

CAP¶

Currently two CAP schemes are supported: M/Chip 4 and M/Chip 2.1. CAP functionalities are supported only with the Thales e-Security HSM device. The Thales e-Security HSM module must be setup to support EMV functionalities (nShield / SPP).

CAP Keys¶

Appropriate CAP keys must be created for an issuer that requires CAP support. The keys must be manually created in the HSM using the key management facilities provided by the HSM vendor.

Issuer keys must follow particular naming conventions as follows:

For M/Chip2.1: cap2mchip< Issuer_ID >
For M/Chip 4: cap4mchip< Issuer_ID >
where < Issuer_Id > specifies the Issuer ID of the corresponding issuer as assigned by ActiveAccess.

When creating the keys select key roles mkac2r and mkac4r for M/Chip 2.1 and M/Chip 4, respectively. You also need to specify a field named IIPB by SPP module which is the AC part of the CAP IPB (Issuer Proprietary Bitmap).

Please refer to 'Key-loading Solutions Guide' by Thales e-Security, for further information on creating and handling keys.

Software Mode¶

For testing purposes only ActiveAccess can run CAP in software emulation mode, without the need for setting up CAP keys in the HSM. The CAP emulation mode is only available for M/Chip 4.

In order to run ActiveAccess in CAP emulation mode, create a text file containing the CAP keys. The file may contain a key entry for each issuer in the form:
```
 <key_alias>=<key_value>
```
where < key_value > is the value of key expressed in hexadecimal format. For example
```
 cap4mchip1234567890=9E15204313F7318ACB79B90BD986AD29
```
Now save the file and give an arbitrary name. Assuming that the file is named 'capkeys.values' and stored in '/opt/activeaccess' directory, you need to all the following line to ActiveAccess start up script:
-Dcom.gpayments.CAPKeys.file = /opt/activeaccess/capkeys.values
Note
Software mode is only provided for test purposes and must not be used in production.
You cannot use CAP in hardware while software mode is enabled. Be sure to remove reference to your CAP key file, if you wish to use hardware for M/Chip 4 or M/Chip 2.1.

CAP Logging¶

CAP uses the global java logger to log the CAP related activities. So by setting the java.util.logging.config.file property to an arbitrary java logging configuration file, you can have different levels of logging (Severe, Warning, Info, Fine, Finer, Finest, All) for CAP authentications. More detail is output when ActiveAccess is run in CAP simulation mode.

RSA¶

To Enable RSA devices, you need to download and copy the RSA Java library file (RSASecurIDAuthenticationEngineAPI.jar) site to the library directory of ActiveAccess application server. You may need to contact RSA Security in order to receive the Java library file.

RSA token keys should be uploaded in the system. These files are provided by RSA and can be uploaded to ActiveAccess using the administration interface.

Browse to System Management > Device Management choose upload file and then specify the file and relevant parameters.

SMS¶

SMS authentication is natively supported by ActiveAccess and does not require additional software. However, ActiveAccess needs to be configured to send SMS messages using SMPP protocol to an SMSC (SMS Centre). ActiveAccess supports SMPP-API-0.3.9.1. An SMSC is normally a gateway to the mobile communication network provided by a Telco or third party service provider.

You need the following details in order to configure SMS authentication in ActiveAccess administration:

Name: A unique name to identify this SMS centre in ActiveAccess

IP: The IP address of the SMS Centre

Port: The port which that SMS Centre is listening on

System ID: The username that is used by SMS Centre for authentication

Password: The password that is used by the SMS Centre for authentication

Sender's mobile number: The mobile number displayed to the message recipient.

Note

Note that to be able to send SMS with templates other than English language or using symbols in SMS Template, you must set following system property in the TOMCAT_HOME/bin/catalina.bat or catalina.sh:

-Dsmpp.default_alphabet=ie.omk.smpp.util.UCS2Encoding

There are two ways to send OTP to SMSC:

MailTo¶

IP: MailTo:$DEVICE_SERIAL_NUMBER@example.com

`$DEVICE_SERIAL_NUMBER will be replaced by ACS with the mobile number that is stored for the card.

Note

To use this option, mail server must be configured in System Management > Settings.

SMS via JMS¶

Approach 1:
IP: SmsViaJms:[IP_ADDR_STAND_ALONE_APP]
Approach 2:
IP: SmsViaJms

Note

Note that to be able to send SMS with templates other than English language or using symbols in SMS Template, you must set following system property in the TOMCAT_HOME/bin/catalina.bat or catalina.sh:

-Dsmpp.default_alphabet=ie.omk.smpp.util.UCS2Encoding

Email OTP¶

Email authentication is natively supported by ActiveAccess and does not require additional software. However, ActiveAccess needs to be configured to send OTP via Email. You need the following details in order to configure Email authentication in ActiveAccess administration:

Mail server address: The address of the mail server

Mail server port: The port which the mail server is listening on

Mail server username: The username that is used by the mail server for authentication

Mail server password: The password that is used by the mail server for authentication

Mail server protocol: The protocol that is used by the mail server for secure communications over the network

Mail sender: The sender's name displayed to the email recipient.

VASCO¶

To enable authentication using VASCO tokens you need to:

Install VASCO native libraries first.
Obtain a copy of Java library 'aal2wrap.java' form VASCO and copy to the lib folder of your ActiveAccess application server.
The native library should be accessible to the java application. For this purpose in UNIX the variable LD_LIBRARY_PATH should contain the address of the native library which normally is /opt/vasco/VACMAN_Controller-3.4/lib.
In Windows the address of the DLL file should be added to the PATH variable. Also the VASCO token keys should be uploaded in the system. These files are provided by VASCO with the devices and can be uploaded to ActiveAccess using the administration interface.
Browse to System Management > Device Management choose upload file and then specify the location of the file and relevant parameters.