3DS Server Operation Manual

Starting/Stopping the 3DS Server

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

Logging

Refer to the Log4j2 Configuration documentation.

Credentials

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:

  • Generating Certificate Signing Request (CSR) (for an existing certificate renewal or for a new certificate)
  • Importing signed certificate in the certificate store
  • Importing/Exporting client certificate store in Java KeyStore (JKS) format
  • Removing certificates

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

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.

  • ClientCertificateStore on level Scheme (XPath in 3dss-configuration.xml:/Scheme/DirectoryServer/ClientCertificateStore):

    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.

  • ClientCertificateStore on level MerchantAcquirer (XPath in 3dss-configuration.xml: /Merchant/MerchantAcquirer/DirectoryServer/ClientCertificateStore) and on level AcquirerBin (XPath in 3dss-configuration.xml: /Acquirer/AcquirerBin/DirectoryServer/ClientCertificateStore)

    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.

Keystore and key pair

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.

Certificate Signing Request (CSR)

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.

Obtaining a signed certificate

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.

Certificate Import

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")

Existing Private Key and Certificate Import

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.

Client Certificate Renewal

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

Server certificates

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.

Apache configuration with multiple virtual hosts with same host names
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>
Apache configuration with multiple virtual hosts with same ports
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>

Trust and Root certificates

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:

  • /Scheme/DirectoryServer/TrustCertificateStore
  • /Acquirer/AcquirerBin/DirectoryServer/TrustCertificateStore
  • /Merchant/MerchantAcquirer/DirectoryServer/TrustCertificateStore

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.

Certificate import

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
Root certificate renewal

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
Root certificate changed

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

3DS Server configuration

Entity configuration (Merchants, Acquirers and Schemes)

Refer to the 3DS Server Configuration documentation for details about the configuration format.

Configuration properties

Refer to the 3DS Server Configuration Properties documentation for details about the configuration options.

Retry mechanism for Preparation Request and Authentication Request to the Directory Server

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.

Reloading the 3DS Server Configuration at runtime

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.

Reloading the 3DS Server License at runtime

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.

Security

Access permissions

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.

Password encryption

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 exposed HTTP endpoints

3DS Server Dashboard endpoints

3DS Server exposes the following endpoints to which access should be restriced from within the PSP environment:

3-D Secure endpoints

3DS Server exposes the following endpoints to which access should be restricted from within the PSP environment:

3-D Secure externally exposed endpoints

3DS Server exposes the following endpoints to which access should be allowed (invoked from the ACS and DS systems):

  • https://<host>:<port>/3ds/3ds-method-notification/
  • https://<host>:<port>/3ds/results-request
  • https://<host>:<port>/3ds/challenge-response

Session handling strategies

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.

Session replication

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.

Errors and troubleshooting

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).

Reporting

Obtain info from the log files

Search the log files using grep command (refer to Log4j2 Configuration documentation for location of the log files).

  • Find error by error description
    grep "Error while trying to communicate with the Directory Server." app.2018-04-03.log
  • Get all log messages connected to 3DS Server Transaction ID
    grep f26f7244-e273-4bce-a0b8-d2cf096f7136 app*.log
  • Navigate to some exception in app.log
    less app.2018-04-03.log

    and search for string (e.g /DsAresValidationException)

  • Navigate to some date
    less app.2018-04-03.log

    and search for date (e.g /2018-04-03 14:39:51,436)

Monitoring the application and gathering metrics

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:

  • Number of requests handled by the application
  • Duration of request processing on 3DS Server side as well as the duration of the 3DS Server - Directory Server communication per request
  • Number of exceptions occurred, distinguished by their type and the message flow in which they occurred (PREPARATION, AUTHENTICATION, RESULTS, etc).

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.

3DS Server Dashboard

The 3DS Server provides a HTML dashboard reachable under /admin/dashboard.

The dashboard shows information about:

  • Performance and failure statistics
  • Errors
  • Configuration
  • License

Note that performance and exceptions statistics will be lost when the 3DS Server application is restarted.

Transactions dashboard

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.

Exceptions dashboard

The exceptions dashboard shows the type and number of exceptions that occurred in the 3DS Server

Acquirers configuration

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.

Merchants configuration

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.

Scheme configuration

The scheme configuration tab shows each configured scheme, including Directory Server configuration. Each scheme is shown in a separate visual container.

URL configuration

The URL configuration tab displays the configured URLs for notification, results response notification, challenge response notification, 3DS Requestor and 3DS Method Notification.

License information

The license information tab shows information for the 3DS Server license, including licensed version and expiry date.