Netcetera MPI
- Overview
- Installation Manual
- Operation Manual
- Integration Manual
Codes
Configuration
Schema
Script
Release Notes
Use the mpictl script to start or stop an MPI node.
Run the script with the -h argument to learn about the available options and commands:
$ $MPI_HOME/bin/mpictl.sh -h
Refer to the Log4j Configuration documentation.
The MPI application uses TLS/SSL client and root certificates stored in Java Key Store (JKS) format.
Keystore files, once created and populated, need to be referenced for usage in the MPI Configuration file.
For creating and manipulating keystores, Java keytool is used. The keytool is part of the Java Development Kit (JDK).
To generate the keystore and the key pair execute the following command:
keytool -genkey -alias client -keyalg RSA -keysize 2048 -keystore client.jks -dname "CN={COMMON NAME},O={ORGANZIATION},L={LOCATION},ST={CITY},C={COUNTRY}"Replace the placeholders in the distinguished name (e.g. COMMON NAME) with the appropriate values for the Merchant or Acquirer.
Change the name of the keystore and the alias as you wish. For this and the following examples client.jks and client are used.
Important: The passwords for the keystore and the key have to be the same in order for the MPI to be able to access the keystore and the key.
The Certificate Signing Request (CSR) can be created with the following command:
keytool -certreq -alias client -file client.csr -keystore client.jks
This command creates the client.csr file from the previously created keystore.
The CSR needs to be sent to the Certificate Authority (CA), in order to receive a valid signed certificate.
Once the client.crt file is obtained from the Certificate Authority, it can be imported into the existing keystore.
First import the CA certificate as a trusted entry:
keytool -import -trustcacerts -alias ca -file ca.crt -keystore client.jks
Then use the following command to import the client certificate:
keytool -import -trustcacerts -alias client -file client.crt -keystore client.jks
For migrating existing client private keys and certificates, export them to PKCS#12 format and then use the Java keytool to import them in JKS format.
Use openssl to create the PKCS#12 file (src.p12) from your client certificate (client.crt), the private key (client.key) and the CA certificate (ca.crt):
$ openssl pkcs12 -export -out src.p12 -inkey client.key -in client.crt -certfile ca.crt
Then import the PKCS#12 file into a Java keystore:
$ keytool -importkeystore -srckeystore src.p12 -srcstoretype PKCS12 -destkeystore client.jks
Note: use the same password when exporting the PKCS#12 file and when creating the destination JKS keystore.
When renewing a client certificate, the existing CSR can be sent to the CA in order to issue a new valid certificate for the same private key.
After the CA responds, the new certificate can be imported into the client keystore. In order not to overwrite any existing valid certificates, first list the available aliases in the key store:
keytool -list -keystore client.jks
If the initial CSR is reused, the client private key already exists in the key store and must be cloned under a new alias:
keytool -keyclone -alias client -dest client-new -keystore client.jks
Note: private key password and keystore password must be the same.
Import the renewed client certificate (client-new.csr) under the newly created alias:
keytool -import -trustcacerts -alias client-new -file client-new.crt -keystore client.jks
Note that the MPI sets the Java Security property ssl.KeyManagerFactory.algorithm to NewSunX509 in order to properly support multiple certificates in the same Keystore. If multiple certificates are available, it prefers valid to expired ones.
Refer to the MPI Configuration documentation for details about the configuration format.
Refer to the MPI Configuration Properties documentation for details about the configuration options.
You should protect the MPI Configuration file using Unix file permissions as it contains keystore passwords.
Make sure the user running the MPI application is still able to read the file.
Passwords (keystore passwords and merchant acquirer passwords) in the MPI Configuration can be obfuscated.
Create an obfuscated password by using the mpitool script as follows:
$ $MPI_HOME/bin/mpitool.sh obfuscate my_password
To make the MPI application aware of using obfuscated passwords, you have to set the corresponding MPI Configuration Property:
mpiConfigXml.useObfuscatedPasswords=true
Multiple MPI nodes can be run in a cluster for:
When starting multiple MPI nodes on the same machine, use the -n command line argument with the mpictl script and specify the node ID.
You have to setup a load balancer to distribute the workload to the MPI nodes in the cluster.
As the MPI maintains a session for the requests in a 3-D Secure transaction, either setup sticky sessions (to ensure the same MPI node receives all requests belonging to the same 3-D Secure transaction) or setup session replication by adjusting your Ehcache Configuration.
Configure your load balancer to use sticky sessions and make sure to send additional Cookies or Header values as needed by your load balancer when sending requests to the MPI.
Before shutting down an MPI node (e.g. for upgrading), make sure that there are no more running transactions (e.g. by instructing your load balancer to not send any new transactions to this node and wait till all running transactions are completed).
As an alternative to using sticky sessions, you can use the MPI's support for session replication.
For details about session replication configuration with the MPI, refer to the Ehcache Configuration documentation.
When using session replication, every MPI node in the cluster may process any request of a 3-D Secure transaction. I.e. every node can resume sessions started on another node.
Exceptions are logged to the MPI application log (see Log4j Configuration for details) on level ERROR.
For every exception during request processing, an error code is logged that can be used to categorize the error.
Refer to the Error Codes documentation for a description of the error codes used by the MPI.
For most error codes the merchant can not intervene. In frequent cases of timeouts when communicating with the Directory Server or while waiting for a response from the ACS, increasing the corresponding timeout should be considered (see also MPI Configuration).
Search the log files using grep command (refer to Log4j Configuration documentation for location of the log files).
grep DS-REST mpi.2013-04-03.log
grep "Error while trying to communicate with the Directory Server." mpi.2013-04-03.log
grep x72RheEAN7TX1Aw5NBQg mpi*.log
or
grep f26f7244-e273-4bce-a0b8-d2cf096f7136 mpi*.log
less mpi.2013-04-03.log
and search for error code (e.g /DS-REST)
less mpi.2013-04-03.log
and search for date (e.g /2013-04-03 14:39:51,436)
Extract the performance statistics from the log files by using the mpictl script command.
$ $MPI_HOME/bin/mpictl.sh -n 1 showstats
The MPI provides an HTML dashboard reachable under /mpi.
The dashboard shows information about:
Note that performance and exceptions statistics will be lost when MPI application is restarted.
When exception occurred in MPI in the last day, alert icon is shown on the dashboard page.
By opening the Exceptions tab, you can check what type of exception occurred.
By clicking on an error row with errors (rows highlighted in red), one can see the details about the last exceptions.
When MPI has already expired or soon to expire certificates configured, alert or warning icon displaying the number of problematic certificates is shown on the dashboard page.
By opening the Certificates tab menu, you can check which configuration elements contain the expired or soon to expire certificates.
When selecting an item of the Certificates tab menu, you can see the detailed information of the keystores containing the expired or soon to expire certificates
When MPI license is no longer valid or is soon to expire, alert or warning icon is shown on the dashboard page.
By opening the License tab, you can check the license.
Alert icon will be shown when either MPI version does not match or the license valid date has passed.
Warning icon will be shown if license is soon to expire.
The MPI exposes various MBeans to facilitate monitoring via JMX.
You can connect to the MPI e.g. by using jconsole which comes bundled with the Java Development Kit (JDK) distribution.
Performance and failure statistics are exposed under org.perf4j:type=StatisticsExposingMBean,name=Perf4J. Check the Perf4j Tags for an overview of the available statistics tags corresponding to operations in the MPI. The statistics information is aggregated over the configured time slice (see Log4j Configuration for details).
For every operation, the following success and failure information is available:
For testing purposes MPI can be configured to be run with Directory Server simulation, in which case the real Verify Enrollment request to the Directory Server will be replaced with fixed response outcomes provided in a properties file.
In order to set the Directory Server simulation mode, enable the dsResponseSimulation configuration property, and provide a property file containing the Directory Server response outcomes.
For the format and the location of the simulation property file check the configuration of dsResponseSimulation.resourceLocation in MPI Configuration Properties documentation.