Installation

Prerequisites¶

• Ensure that a compatible JDK is installed

• Ensure that the hardware security module is properly installed and configured

  HSM keys

  If this is a first time installation, ActiveAccess keys will be generated automatically.

  For subsequent installations of ActiveAccess on other servers ensure that the AES (128 Bits) key alias AA_MASTER has been transferred from the primary installation in the current instance of HSM used by the ActiveAccess which is being installed.

• Ensure that the application server is properly installed and configured

• Ensure that the database server is properly installed and you have created a database for ActiveAccess.

  Database details

  Have the database name, username and password and address at hand for the installation process.

Pre Installation Configurations¶

Upgrades¶

For upgrades from any version of ActiveAccess to the latest version of ActiveAccess, follow the steps below.

• If you have previously deployed enrolment.war to your application server, you must remove it.

  For example, for Tomcat, go to TOMCAT_HOME/webapps, and remove the enrolment.war file and the deployed enrolment directory.

• Go to TOMCAT_HOME/lib. If the following files exist, back up and remove them:

  • gpcomp.pki-*.jar
  • gpcomp.hsm-*.jar
  • spp-*.jar
  • nfjava-*.jar
  • lunaprovider-*.jar
  • kmjava-*.jar
  • kmcsp-*.jar
  • jprov-*.jar
  • commons-codec-*.jar
  • aal2wrap-*.jar

• It is recommended to replace the HSM-related JAR files provided by ActiveAccess, with the libraries provided by your HSM provider. Note that the name of the replacement JAR files must be exactly the same as the name of the JAR files in the ActiveAccess installation package. For example, the jprov.jar file that is provided by your HSM provider may need to be renamed to jprov-1.1.jar.

Upgrades to v8.5.x and later¶

For upgrades to ActiveAccess 8.5.x and later, all clients must have PKCS #11 configured for connectivity to the HSM (this excluses ActiveAccess installations with SunJCE).

• If your ActiveAccess installation already uses PKCS #11 (HSMPROVIDER=PKCS11), no changes are required. This would be the case if the first version of ActiveAccess that you installed was 7.4.x or later.

• If your ActiveAccess installation does not utilise PKCS #11 (i.e. the first version of ActiveAccess that you installed was version 7.3.x or older, with HSMPROVIDER=ERACOM, HSMPROVIDER=nCipherKM, or HSMPROVIDER=LunaProvider), you must add the following attributes in activeaccess.properties and set an appropriate value for them:

  • MASTER_HSM_LIB_DIR=
  • MASTER_HSM_SLOT=
  • PKCS11_CONFIG_FILE_PATH=

  Note

  If you are migrating to a new HSM device, the values set for the attributes MASTER_HSM_LIB_DIR, MASTER_HSM_SLOT, and PKCS11_CONFIG_FILE_PATH must be for the new HSM device.

Upgrades from v7.x.x to v8.x.x and later¶

If you are upgrading from ActiveAccess v7.x.x, in addition to the upgrade steps above, follow the steps below.

• An AA_HOME directory is required from which ActiveAccess will load the configurations it requires for installation. Create a directory and set an AA_HOME environment variable to this directory.

  Note

  Refer to your Operating System and application server documentation for any specific instructions for setting an environment variable.

  • AA_HOME can be set in Tomcat in catalina.bat/catalina.sh as JAVA_OPTS
  • AA_HOME can be set in WebLogic in setDomainEnv.cmd or startWebLogic.sh

• Add the following line in AA_HOME/activeaccess.properties

  HSM_PASSWORD= < password >

  Replace < password > with the base64 encoded format of your HSM password.

  Warning

  After the installation, a new configuration file, activeaccess.properties, will be created automatically in the AA_HOME directory. This new configuration file combines acsconfig.properties, miaconfig.properties and regconfig.properties and these files will be removed during the installation process.

  If you have configured any parameters that are not specific to ActiveAccess, you must take a back up of these files before running the installation and move these parameters manually to activeaccess.properties.

New installations¶

• An AA_HOME directory is required from which ActiveAccess will load the configurations it requires for installation. Create a directory and set an AA_HOME environment variable to this directory.

  Note

  Refer to your Operating System and application server documentation for any specific instructions for setting an environment variable.

  • AA_HOME can be set in Tomcat in catalina.bat/catalina.sh as JAVA_OPTS
  • AA_HOME can be set in WebLogic in setDomainEnv.cmd or startWebLogic.sh

• In the installation package, go to the ActiveAccess directory, copy activeaccess.properties to your AA_HOME directory.

• Open activeaccess.properties and fill in the required configuration parameters.

• It is recommended to replace the HSM-related JAR files provided by ActiveAccess, with the libraries provided by your HSM provider. Note that the name of the replacement JAR files must be exactly the same as the name of the JAR files in the ActiveAccess installation package. For example, the jprov.jar file may need to be renamed to jprov-1.1.jar.

Deploying WAR Packages¶

Download and extract the ActiveAccess installation package from GPayments MyAccount > ActiveAccess > Download.

Access Control Server, Administration Server, Registration Server and Whitelist Server are distributed in the ActiveAccess installation package as WAR packages. To install these packages, deploy acs.war, mia.war, registration.war and whitelist.war packages from ActiveAccess/files to your application server.

Installation¶

To initialize the installation process, start the application server.

This process may take a couple of minutes to complete.

An installation log will be created in AA_HOME/logs/install_log.log.

The date or size of [full path of the config file in installation package]
is different from [full path of the config file in AA_HOME], compare the
content and make sure all the required and optional parameters are OK.

Installation of Individual Components¶

The Access Control Server handles greater loads than other components and may be installed on a physical machine, dedicated to transaction processing.

Administration, Registration and Whitelist servers are usually installed on the same physical machine.

To install individual components:

• Ensure that you have the prerequisites properly installed and configured for each component that is being installed individually.

• Deploy the component's WAR package to the application server.

  • Access Control Server: acs.war
  • Administration Server: mia.war
  • Registration Server: registration.war
  • Whitelist Server: whitelist.war

• Configure the installation parameters (AA_HOME directory and configuration file).

• Start the application server.

• Ensure that the AES (128 Bits) key alias AA_MASTER exists in the HSM.

  Tip

  If this is a first time installation, ActiveAccess keys will be generated automatically.

  For subsequent installations of ActiveAccess on other servers ensure that the AES (128 Bits) key alias AA_MASTER has been transferred from the primary installation in the current instance of HSM used by the ActiveAccess which is being installed.

Rollback Process¶

In case you need to roll back to the previous version, follow the steps below:

1. Shutdown all ActiveAccess servers and stop the applications in the application server.
2. Restore the original database.
3. Restore ActiveAccess directories and deploy the previous version of the applications on your application server locations.

Post Installation¶

• If you upgraded to ActiveAccess v9.0.x from an older version, you must run the Migrate to Data Key Utility and ensure the key migration process completes successfully.

  Note

  This utility does not need to be run for new installations of ActiveAccess v9.0.x.

  Warning

  It is strongly recommended to start the key migration process as soon as possible. Running this utility is critical to upgrading to future versions of ActiveAccess. Old keys (RSA, CAVV, AAEV, HMAC, HMAC256, encryption keys) and old Issuer Signing Certificates will not be supported in future releases of ActiveAccess beyond January 2022.

  If you have any questions in regards to the above, please contact techsupport@gpayments.com.

• On successful installation and when the application server is started, the internal components are started on the default port. These components are:

Access Control Server¶

Base URL: https://< server-address >:< port >/acs/

The following extensions can be added to the base URL:

3DS Method URL: https://< server-address >:< port >/acs/tdsmethod

Monitoring the availability of ACS: https://< server-address >:< port >/acs/ping

Administration Server¶

Base URL: https://< server-address >:< port >/mia/

Monitoring the availability of MIA: https://< server-address >:< port >/mia/ping

Registration Server¶

Base URL: http(s)://< server-address >:< port >/registration/

The Registration Server has received a GET.

Your signed XML (application/xml) should be sent via HTTP POST.

The following extensions can be added to the base URL:

Monitoring the availability of Registration: http(s)://< server-address >:< port >/registration/ping

Whitelist Server¶

Base URL: http(s)://< server-address >:< port >/whitelisting/wl/api/merchant/

Login to the Administration Server as an Administrator user and set the Whitelist server URL in System Management/Settings to the base URL of the Whitelist server. The Whitelist Server accepts HTTP Post commands for the purpose of adding/displaying/removing cardholder’s whitelisted merchant data.

The following extensions can be added to the base URL:

Configuration Files¶

ActiveAccess Configuration File¶

AA_HOME/activeaccess.properties

The ActiveAccess Configuration file, activeaccess.properties, is automatically created/updated by the ActiveAccess installation. Common options such as database information are required to be configured during installation. The following sections document all the available parameters in case you need to change the defaults.

Common Configuration Parameters¶

DBNAME, DBOWNERPASSWORD

This is the database owner name and password that you use to create the database. When you first set or change the database owner password, you may set it in clear text. You should also add (PLAIN_TEXT=) to your configuration file.

DBUSERNAME, DBPASSWORD

This is the username and password that you use to access the database. In a simple configuration this username may be the same as the database owner name. When you first set or change the database password, you may set it in clear text. You should also add (PLAIN_TEXT=) to your configuration file.

PLAIN_TEXT=

This instructs the server to read DBOWNERPASSWORD and DBPASSWORD in clear text and replace them with the encrypted values.

DBURL

For Oracle the default URL is:

jdbc\:oracle\:thin\:\@127.0.0.1\:1521\:ORCL

Replace 127.0.0.1:1521 with the IP address and port number of the Oracle instance you have installed. ORCL is the SID of the database and must be replaced with the SID you selected during the installation of the database server.

DBURL=jdbc\:oracle\:thin\:\@192.168.0.202\:1521\:ORCL

DBDRIVER

For Oracle, leave the default value unchanged as shown below:

DBDRIVER=oracle.jdbc.driver.OracleDriver

INITIALCONNECTIONS

Specifies the initial length of database connection pool allocated by the application.

MAXCONNECTIONS

Specifies the maximum length of database connection pool that can be allocated by the application.

WAITIFBUSY

Can be set to either true or false. The default is true. When set to true, connection requests exceeding the maximum connections will be queue until a connection is freed. When set to false, the application immediately returns an connection erorr if no free connection can be found in the pool.

DB_IDLE_TIMEOUT

The database idle connection time out in seconds. Idle database connections are closed in the application's connection pool after the specified time. The default is 900 seconds.

DBENCODED

If this parameter sets to false reading and writing to database is done in ISO-8859-1 character set and ActiveAccess uses its own encoding (Default value is false). Otherwise database's own encoding is used.

HSMPROVIDER

Used to specify the HSM provider name.

For ActiveAccess instances which were originally installed prior to ActiveAccess v7.4.0, the value would be nCipherKM for Thales e-Security, ERACOM for SafeNet, or SUN for Sun JCE. In ActiveAccess instances originally installed after and including v7.4.0, this parameter would be PKCS11 or SUN.

KEYSTORE_DIR

Used to specify the physical location of the HSM KeyStore (Thales e-Security or SunJCE). Use forward slash as the path separator e.g.: KEYSTORE_DIR=c:/nfast/kmdata/local

PKCS11_CONFIG_FILE_PATH

Used to specify the path to the PKCS #11 configuration file with a .properties extension.

The contents of the configuration file should contain library, slot and name parameters.

nShieldHSM

Only if you are using an nShield HSM, set the value to Yes. For all other HSM types, it should be left blank.

HSM_PASSWORD

Used to set the HSM password in the configuration file. This option takes precedence over the java option -Dcom.gpayments.hsm.password. The HSM password must be provided in base64 encoded format in both cases. Leave empty for a blank HSM password.

HSM_LIB_DIR

Used to specify the path of .dll or .so file which will be added to pkcs11config.properties file, if the file does not exist.

HSM_SLOT

Used to specify the slot number that will be added to pkcs11config.properties file, if the file does not exist.

MASTER_HSM_LIB_DIR

Used to specify the path of .dll or .so file which will be added to pkcs11config.properties file, if the file does not exist. This will be used for saving the Master Key in the HSM.

MASTER_HSM_SLOT

Used to specify the slot number that will be added to pkcs11config.properties file, if the file does not exist. This will be used for saving the Master Key in the HSM.

HSMENCALIAS

When the MIA/ACS Settings Encryption Key is automatically or manually retired and replaced with a new one using the PCIDSS Key Retiring Utility, the default key alias is changed. Therefore, the new key alias is specified by HSMENCALIAS.

WS_POOL

Used to specify the size of WebSocket pool. The default value is 1000.

TOMCAT_KEYSTORE

Used to specify the path of the Tomcat KeyStore in case the timeout error fails with SSL Handshake in browser-based authentication.

TOMCAT_KEYSTORE_PASS

Used to specify the password of the Tomcat KeyStore in case TOMCAT_KEYSTORE is set.

TOMCAT_TRUSTSTORE

Used to specify the path of the Tomcat TrustStore in case the timeout error fails with SSL Handshake in browser-based authentication and the SSL connection is not one-sided.

TOMCAT_TRUSTSTORE_PASS

Used to specify the password of the Tomcat TrustStore in case TOMCAT_TrustStore is set.

CARD_MOD_10_CHECK

Used to enable/disable mod 10 check when creating cards via the administration interface, for testing purposes. It can be set to true or false. The default value is true.

TESTING_MODE

Can be set to either true or false. Set it to true during certification testing. Default value is false.

PROVIDER_TEST

Can be set to either true or false. Set it true during certification test only if the test card bin is not supported in default providers.xml file. If set true providers_test.xml should be created and placed at AA_HOME.

TEST_AUTH_SERVER

Set URL of authentication server. This parameter is developed to support UL tests.

ACS_REFERENCE_NUMBER_TEST

Set ACS reference number during certification test.

TIMEZONE_ID

Used to set the time zone of the application.

Refer to ActiveAccess/timezones.txt which has a list of acceptable time zones.

AMOUNT_FORMATTER

Used to set the reference for the transaction amount format in SMS, email, and authentication pages. The default is STANDARD.

Values:

• STANDARD: The US-English standard, which includes a comma as the thousands separator and a dot as the exponent separator.
• LOCALISED: The local value derived from the installed server. In case the user.language.format and user_country_format are not set, the default local of the system will be used.

IGNORE_DTD_ORDER_3DS1

Used to enable/disable the checking of the order of the elements provided in 3DS1 requests. The default is false.

Values:

• true: The order of the elements will not be checked.
• false: The order of the elements will be checked.

MD_VALIDATION_3DS1

Used to enable/disable the validation of the MerchantData element in JCB 3DS1 transactions. The default value is true.

Values:

• true: MerchantData element will be validated.
• false: MerchantData element will not be validated.

PURCHASE_DATE_ACCEPT_BALANCE

Used to configure the balance of the purchase date validation. The validation is disabled by default, unless configured.

• Accepted range: 60 to 1440 (1 hour to 1 day in minutes).

Additional Administration Server Configuration Parameters¶

UPLOADCACHE_DIR

Used to specify a location to copy uploaded file that VASCO tokens fetched from it. Use forward slash as a path separator e.g.: UPLOADCACHE_DIR=c:/tempdir

MAX_WARNINGS

Specifies the maximum number of warning messages that the administration server will generate while processing VASCO token files before an error is returned. In other words, if processing a VASCO file creates more warnings than this value, the server will terminate processing of the file and will return an error response. If this parameter is not specified, a default value of 50 is used.

Additional ACS Configuration Parameters¶

COMPUTERNAME

This is the computer name where the ACS is installed.

DOMAINNAME

This is the domain name where the ACS is installed. It must be resolved to an IP address and you must add this host name to /etc/hosts or in Windows C:\WINDOWS\system32\drivers\etc\hosts before installation.

BINDING_IP_ADDRESS

Used to define the binding IP address of ActiveAccess.

RMI_PORT

The RMI port of ActiveAccess. The default value for the RMI port is 4242. If you decide to change the RMI port, you can edit this value at any time.

AHS_FLAG

Used to enable/disable Authentication History Server. It can be set to either true or false. The default value is true.

CACHING

This option specifies the caching mode for resources. The default is everyvisit.

DBENCODED

Can have two values Yes or No. If your Database is set to use encoding, set this option to Yes.

ZLIBOFF

It can be set to either true or false. When it is set to true, ACS does not inflate ZIP objects. The default value is false.

Additional Registration Server Configuration Parameters¶

VERIFICATION

Can be set to either true or false. When the verification is true, the registration server checks the authenticity of XML messages by validating the XML signature. Disabling verification should be avoided in a production system for security reasons.

REQUEST_LOGGING

Can be set to either true or false. Used to collect request debug information, intended for testing purposes. This option should not be enabled in production environment.

MAX_WARNINGS

Specifies the maximum number of warning messages that the registration server will generate, before an error is returned. In other words, if a message sent to the registration server creates more warnings than this value, the server will terminate processing the message and will return an error response. If this parameter is not specified the default value of 50 is used.

Notification Report Collector Job Parameters:

Notification Reports are provided based on collected report files by the Notification Report Collector Job on the Registration server. In order to configure this job to collect the required data and cache report files, the following parameters must be set in activeaccess.properties:

LAST_REPORT_TIME

The last time that the notification report collector job was run

Format: DD/MM/YYYY

OFFICIAL_START_HOUR (Deprecated and is no longer used)

The hour that is used as the start hour of the day. Reports are collected based on this hour. Values: 00..23 (default: 00)

OPTOUT_MODE

The flag that specifies whether report collector should collect the last cardholder opt out only or all opt outs.

Values: LAST/ALL (default: ALL)

SCHEDULER_START_TIME

The time that the report collector job starts to collect reports based on LAST_REPORT_DATE

Format: HH:mm:ss GMT(+0:00) (default: -1 to disable job).

Example: Assume LAST_REPORT_TIME=02/02/2009, SCHEDULER_START_TIME=22:30:30, if today is 05/02/2009, report collector starts at 22:30:30 GMT(+0:00) and collects reports from 02/02/2009 00:00 to 05/02/2009 00:00

NOTIFICATION_FILE_PATH

The path on the server which the report collector job will cache for the collected report files

The default path is a NotificationReport directory, located in the deployed directory of Registration on your application server.

NOTIFICATION_REPORT_LIFETIME

The life time of cached report files on the server in DAY. As soon as the report collector job starts, it removes files if their life time period has already passed

Default: -1 to disable

NOTIFICATION_REPORT_REGEN_ISSUERIDS

A comma separated list of the IDs of the issuers that have retired their encryption key using PCIDSS Retiring Utility. As the result of retiring the encryption key of an issuer, the pre-collected notification report files are no longer valid. This list is automatically populated at the end of the utility process to indicate that notification reports should be re-collected for the specified issuers at the next run of the notification report collector job.

Providers File¶

ActiveAccess requires the default card ranges of all providers in order to process incoming 3D-Secure authentication requests. As card schemes may add new card ranges at any time, the providers file allows for the additions to be made manually, when required. The following options can be updated in providers.xml under the AA_HOME directory.

• Provider name, provider index, cname and provider ID: within the < providerInfo > element for each of the providers, there are tags for the provider's name (< providerName >), index (< providerIndex >), card scheme authentication method (< cName >), and provider ID (< providerId >). The following table shows the possible values for the aforementioned tags.

• Card Range: the card ranges for each provider are included in the providers file, in the form of minimum range and maximum range. The minimum range should always be lower than', or equal to, the maximum range, with an equal number of digits. You can add any card range to the providers file inside the tag, by copying the tag and inserting the new minimum and maximum ranges. Make sure the newly added card ranges do not overlap with another provider's card ranges. Furthermore, the tag indicates the required number of digits for card numbers, which fall within the specified card range.