Netcetera 3DS MPI
- Overview
- Installation Manual
- Operation Manual
- Integration Manual
- Product Home-Page
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).
The keytool expects certificates to be imported in either DER format or PEM format (Base64 encoded DER format).
MPI distinguishes 2 types of client certificates:
Points to a keystore containing a certificate and a private key which are used during the Verify Enrollment phase, when the MPI is communicating to the Directory Server on behalf of the merchant. It is used by the Directory Server to authenticate the merchant. If the merchant is authenticated by username and password, this field may be left out empty. ClientCertificate on level Merchant takes precedence over ClientCertificate on Acquirer level (see below), when resolving which keystore to use.
Merchants are associated with acquirers. Merchants may authenticate to the Directory Server using the ClientCertificate defined on level Acquirer. If there is no ClientCertificate defined on Merchant level, the Acquirer ClientCertificate is used.
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.
MPI distinguishes 2 types of root certificates:
Points to a keystore containing a root and all intermediate certificates which are used during the Verify Enrollment phase to verify the SSL server certificate presented by the Directory Server.
Points to a keystore containing a certificate which is used during the Payer Authentication phase, when the MPI verifies the validity of the digitally signed XML received from the ACS.
Once the root.crt file is received, it can be imported into a keystore. Use the following command to import the root certificate:
keytool -import -trustcacerts -alias root -file root.crt -keystore trusted-root.jks
On the prompt, when asked if this certificate should be trusted, enter: yes.
Verify that the certificate and the alias have been added to the keystore:
keytool -list -keystore trusted-root.jks -alias root
If the TrustedRootCertificate or the SignatureValidationRootCertificate are nearing the expiration date, a new certificate may be added to the respective keystore.
Given a keystore file named "trusted-root.jks", first list all aliases in the keystore:
keytool -list -keystore trusted-root.jks
Given new certificate file named "new-certificate.crt", existing alias name "root" and new alias "root-new", importing the certificate is done with the following command:
keytool -import -trustcacerts -alias root-new -file new-certificate.crt -keystore trusted-root.jks
On the prompt, when asked if this certificate should be trusted, enter: yes.
Verify that the certificate and the alias have been added to the keystore:
keytool -list -keystore trusted-root.jks -alias root-new
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.
If the root certificate (TrustedRootCertificate or SignatureValidationRootCertificate) are no longer valid, they should be removed from the keystore and a new valid certificate should be imported.
Given a keystore file named "trusted-root.jks", first list all aliases in the keystore:
keytool -list -keystore trusted-root.jks
Given new certificate file named "new-certificate.crt" and existing alias name "root" first we remove the old invalid certificate.
keytool -delete -alias root -keystore root.jks
Then we import the new valid certificate:
keytool -import -trustcacerts -alias root -file new-certificate.crt -keystore trusted-root.jks
On the prompt if this certificate should be trusted, enter: yes.
Verify that the certificate and the alias have been added to the keystore:
keytool -list -keystore trusted-root.jks -alias root-new
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/dashboard.
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.