Use the 3dsctl script to start or stop a 3DS Server node.
Run the script with the -h option to learn about the available options and commands:
$ $THREEDS_HOME/3ds-server/bin/3dsctl.sh -h
Refer to the Log4j2 Configuration documentation.
The 3DS Server application uses TLSv1.2 client and root certificates.
The configuration of the 3DS Server client certificates depends on the 3DS Server Configuration type. When the 3DS Server uses database persisted configuration, the 3DS Server Admin Web application can be utilised for the certificates configuration. The 3DS Server Admin Web application allows:
Visit 3DS Server Admin Client Certificate Store configuration for the procedure of configuring and managing the 3DS Server client certificate store.
When using 3DS Server XML configuration, the 3DS Server TLSv1.2 client and root certificates are stored in Java KeyStore (JKS) format. Keystore files, once created and populated, need to be referenced for usage in the 3DS Server Configuration file as part of the DirectoryServer configuration.
For creating and managing 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).
Client certificates can be defined in 3DS Server Configuration anywhere under the DirectoryServer configuration element. DirectoryServer can be configured under Scheme, AcquirerBin and MerchantAcquirer configuration.
Points to a keystore containing a certificate and a private key which are used when sending requests to the Directory Server. These requests are: Preparation Request, Authentication Request, Results Response and Protocol Error. If no configuration is set on AcquirerBin and MerchantAcquirer level, the ClientCertificateStore will be resolved from the Schema configuration.
Merchants are associated with acquirer BINs via the MerchantAcquirer configuration. Merchants may authenticate to the Directory Server using the ClientCertificateStore defined on level MerchantAcquirer. The ClientCertificateStore configuration on AcquirerBin level will be associated to all Merchants configured with that AcquirerBin.
NOTE: The ClientCertificateStore with highest precedence is the one configured under MerchantAcquirer. If no configuration is set, it will be inherited from the associated AcquirerBin. If no ClientCertificateStore configuration is present for AcquirerBin, then it will be inherited from the associated Schema configuration.
To generate the keystore and key pair execute the following command:
keytool -genkey -alias client -keyalg RSA -keysize 2048 -keystore client.jks -dname "CN={COMMON NAME},O={ORGANIZATION},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 3DS Server 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 (generated in the previous step) needs to be sent to the Directory Server for the given scheme 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
NOTE: It is important that the certificate is imported under the same alias as the existing alias with the private key. (i.e. in this case the alias is "client")
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 keystore:
keytool -list -keystore client.jks
If the initial CSR is reused, the client private key already exists in the keystore 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
For 3-D Secure requests initiated by the DirectoryServer, the 3DS Server need to establish a secure connection with the DirectoryServer. The connection need to be secured using mutual authentication. The server certificates are signed by the DirectoryServer's CA. The Requestor shall configure the environment to validate the certificates sent by the DirectoryServer or ACS.
We recommend configuring a virtual host for each DirectoryServer configured in the 3DS Server Configuration. Here is an example of an Apache configuration with virtual hosts for each DirectoryServer. In this example, the host name is the same, but the port is different.
It can also be configured to have different host names on the same port, or different host names with different ports. It is important the host name for the virtual host to match with the hostname configured under threeDSServerUrl configured for each DirectoryServer in the 3DS Server Configuration.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | <Location /3ds-server/3ds/results-request> # Require mutual authentication for the specified path SSLVerifyClient require</Location># Host name is the same in both VirtualHost configurations, the ports are different<VirtualHost hostname.3ds.server:443> SSLEngine on SSLCACertificateFile /path/to/scheme-1/server/certificate/3dss-ca-scheme1.crt SSLCertificateFile /path/to/scheme-1/server/certificate/3ds-server1.crt SSLCertificateKeyFile /path/to/scheme-1/server/certificate/3ds-server1.key</VirtualHost><VirtualHost hostname.3ds.server:11443> SSLEngine on SSLCACertificateFile /path/to/scheme-2/server/certificate/3dss-ca-scheme2.crt SSLCertificateFile /path/to/scheme-2/server/certificate/3ds-server2.crt SSLCertificateKeyFile /path/to/scheme-2/server/certificate/3ds-server2.key</VirtualHost> |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | <Location /3ds-server/3ds/results-request> # Require mutual authentication for the specified path SSLVerifyClient require</Location># Host names are different in both VirtualHost configurations, the ports are the same<VirtualHost scheme-1.hostname.3ds.server:443> SSLEngine on SSLCACertificateFile /path/to/scheme-1/server/certificate/3dss-ca-scheme1.crt SSLCertificateFile /path/to/scheme-1/server/certificate/3ds-server1.crt SSLCertificateKeyFile /path/to/scheme-1/server/certificate/3ds-server1.key</VirtualHost><VirtualHost scheme-2.hostname.3ds.server:443> SSLEngine on SSLCACertificateFile /path/to/scheme-2/server/certificate/3dss-ca-scheme2.crt SSLCertificateFile /path/to/scheme-2/server/certificate/3ds-server2.crt SSLCertificateKeyFile /path/to/scheme-2/server/certificate/3ds-server2.key</VirtualHost> |
3DS Server has only one type of root and trust certificates, that is defined under TrustCertificateStore in the following paths in the 3dss-configuration.xml:
The TrustCertificateStore is used to store the root Certificate Authority (CA) certificates. If the root CA certificate is a public certificate already trusted by JAVA, this keystore may be omitted.
The TrustCertificateStore may contain the DirectoryServer CA certificate, just to separate the CA certificates from the client certificates.
TrustCertificateStore configuration may also reference the same keystore file as the ClientCertificateStore configuration.
NOTE: The TrustCertificateStore with highest precedence is the one configured under MerchantAcquirer. If no configuration is set, it will be inherited from the associated AcquirerBin. If no TrustCertificateStore configuration is present for AcquirerBin, then it will be inherited from the associated Schema configuration.
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 root certificate is 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
If the root certificate is no longer valid, it 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 3DS Server Configuration documentation for details about the configuration format.
Refer to the 3DS Server Configuration Properties documentation for details about the configuration options.
Directory servers can be configured with multiple directory server endpoints, so that in case of a failure in one - 3DS Server can try contacting the next available endpoint.
According to the EMVCo 3-D Secure specification for Preparation and Authentication requests, if a timeout has occurred while invoking the request to the DirectoryServer , the 3DS Server will retry using the next available endpoint. If only one endpoint is configured for the DirectoryServer, the same one will be used in the retry attempt.
For Preparation requests, when the retry mechanism is triggered, the 3DS Server will send the PReq message to the DirectoryServer in an interval of 60 seconds until a message is received from the DirectoryServer. Then it will switch back in a normal mode of operation.
The 3DS Server supports reloading the 3DS Server Configuration without restarting it.
NOTE: The 3DS Server exposes an endpoint http://<host>:<port>/reload/config which can be used to reload the configuration using a HTTP POST request. An additional dryRun=true request parameter can be sent to the endpoint to have the 3DS Server only validate the 3DS Server configuration without actually reloading it.
For convenience, the 3dsctl.sh script can be used with the following command to validate the 3DS Server configuration:
$ $THREEDS_HOME/bin/3dsctl.sh -n 1 configtest
After the new configuration has passed the validation, the 3DS Server Configuration can be reloaded with the following command:
$ $THREEDS_HOME/bin/3dsctl.sh -n 1 configreload
NOTE: The script will parse the node-$NODE_ID.properties found in the $THREEDS_HOME/conf folder to resolve the port. In case the node ID parameter is not passed, the 3DS Server will resolve the node ID to 1. If the server.port is not configured in $THREEDS_HOME/conf/node-1.properties, the 3DS Server will try to resolve it from $THREEDS_HOME/conf/application.properties. It will then send an HTTP POST request (using curl) to the config-reloading-endpoint.
NOTE: The configtest and configreload commands apply to only one 3DS Server node. The -n option is used to specify the 3DS Server node that should reload the configuration. In a setup with more than one 3DS Server node, the reloading of the 3DS Server Configuration must be performed on all nodes. Before issuing the configreload command, make sure that all 3DS Server nodes use or have the same 3DS Server Configuration.
The 3DS Server supports reloading the 3DS Server License without restarting the 3DS Server.
NOTE: The 3DS Server exposes an endpoint http://<host>:<port>/reload/license which can be used to reload the license using an HTTP POST request. An additional dryRun=true request parameter can be sent to the endpoint to have the 3DS Server only validate the 3DS Server license without actually reloading it.
For convenience, the 3dsctl.sh script can be used with the following command to validate the 3DS Server license:
$ $THREEDS_HOME/bin/3dsctl.sh -n 1 licensetest
After the new license has passed the dryRun reloading, the 3DS Server License can be reloaded with the following command:
$ $THREEDS_HOME/bin/3dsctl.sh -n 1 licensereload
NOTE: The script will parse the node-$NODE_ID.properties found in the $THREEDS_HOME/conf folder to resolve the port. In case the node ID parameter is not passed, the 3DS Server will resolve the node ID to 1. If the server.port is not configured in $THREEDS_HOME/conf/node-1.properties, the 3DS Server will try to resolve it from $THREEDS_HOME/conf/application.properties. It will then send an HTTP POST request (using curl) to the license-reloading-endpoint.
NOTE: The licensetest and licensereload commands apply to only one 3DS Server node. The -n option is used to specify the 3DS Server node that should reload the license. In a setup with more than one 3DS Server node, the reloading of the 3DS Server License must be performed on all nodes.
You should protect the 3DS Server Configuration file using Unix file permissions as it contains keystore passwords.
Make sure the user running the 3DS Server application is still able to read the file.
Keystore passwords in the 3DS Server Configuration can be encrypted.
The encrypted passwords must be created using the 3dstool script as follows:
$ $THREEDS_HOME/3ds-server/bin/3dstool.sh encrypt my_password
As additional precaution, if using same password in multiple occurrences, run the tool for each occurrence to generate a different encrypted value.
To make the 3DS Server application aware of using encrypted passwords, you have to set the corresponding 3DS Server Configuration Property:
$ threedsserver.configuration.use-encrypted-passwords=true
The default value for this property is false, meaning that plain-text passwords are used. When using the 3DS Server with database configuration, keystore passwords are always encrypted.
3DS Server exposes the following endpoints to which access should be restriced from within the PSP environment:
3DS Server exposes the following endpoints to which access should be restricted from within the PSP environment:
The 3DS Server needs to maintain data between the versioning and authentication calls or the 3DS transactions. You should choose the session handling strategy that best suits your setup. Session replication can be used in a cluster setup where the 3DS Server internally maintains a session.
You can use the 3DS Server's support for session replication, where EhCache is used as a session replication service.
For details about session replication configuration with the 3DS Server, refer to the Ehcache Configuration documentation.
When using session replication, every 3DS Server 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 3DS Server application log (see Log4j2 Configuration for details) on level ERROR.
For every exception during request processing, an error code is set so that can be used to categorize the error.
Refer to the EMVCo 3-D Secure documentation for a description of the error codes used by the 3DS Server.
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 DirectoryServer, increasing the corresponding timeout should be considered (see also 3DS Server Configuration).
Search the log files using grep command (refer to Log4j2 Configuration documentation for location of the log files).
grep "Error while trying to communicate with the Directory Server." app.2018-04-03.log
grep f26f7244-e273-4bce-a0b8-d2cf096f7136 app*.log
less app.2018-04-03.log
and search for string (e.g /DsAresValidationException)
less app.2018-04-03.log
and search for date (e.g /2018-04-03 14:39:51,436)
In order to monitor the application, the 'metrics' and 'health' endpoints are publicly exposed and available on http(s)://<host>:<port>/actuator/metrics and http(s)://<host>:<port>/actuator/health. However, these endpoints should be restricted from within the PSP environment.
There are Spring built-in metrics, as well as several 3DS Server specific metrics. The metrics provide info about:
Each particular metric can be accessed via http(s)://<host>:<port>/actuator/metrics/<metric-name>.
There is a possibility to publish the metrics on a third-party monitoring systems which allow visualization and querying of the results, math operations, etc.. The Prometheus monitoring system is incorporated with the 3DS Server, but is disabled by default. In order to enable it set the management.metrics.export.prometheus.enabled property to true and add the prometheus endpoint to the publicly exposed actuator endpoints property - management.endpoints.web.exposure.include in 3DS Server Configuration Properties.
Upon request, other monitoring systems such as Atlas, Datadog, etc. can be incorporated with the 3DS Server.
The 3DS Server provides a HTML dashboard reachable under /admin/dashboard.
The dashboard shows information about:
Note that performance and exceptions statistics will be lost when the 3DS Server application is restarted.
The transactions dashboad shows statistics for /3ds/* exposed endpoints and preparation requests. It displays number of requests, average, max and min and total time of each category.
The exceptions dashboard shows the type and number of exceptions that occurred in the 3DS Server
The acquirers configuration tab shows each configured acquirer information, including acquirer BINs and Directory Server configuration. Each acquirer is shown in a separate visual container, and each BIN associated to the acquirer is displayed in an accordion container, with a header showing the scheme and acquirerBIN value.
The merchants configuration tab shows each configured merchant information, including merchant acquirer configuration and Directory Server configuration. Each merchant is shown in a separate visual container, and associated acquirer to is displayed in an accordion container, with a header showing the acquirer merchant name.
The scheme configuration tab shows each configured scheme, including Directory Server configuration. Each scheme is shown in a separate visual container.
