Configuring Certificates for Dispatcher Paragon Payment System

This guide provides information about the certificates used in Dispatcher Paragon Payment System and its clients.

Introduction

By default, Payment System uses a built-in certificate generated by the Y Soft CA and accepts secure SSL connections only. This applies to web interfaces (Dispatcher Paragon Payment System Cash Desk, Dispatcher Paragon Payment System Wallet and Dispatcher Paragon Payment System Administration web) and REST API access.

Other Dispatcher Paragon components (Terminal Server, Spooler Controller, Dispatcher Paragon End User Interface) are configured to accept this certificate exclusively when communicating with the Dispatcher Paragon Payment System server.

The private key is stored in <PAYMENT_HOME>\payment-conf\keystore.jks and protected with a password, which is saved in plain text and visible in the Tomcat configuration XML <PAYMENT_HOME>\conf\server.xml.

PAYMENT_HOME is typically located at C:\DispatcherParagon\YPS.

With knowledge of/access to the private key, it is possible to decrypt traffic and gain administration access to the Dispatcher Paragon Payment System API (including possibilities to make money transactions). This may be a potential danger as all Dispatcher Paragon Payment System installation packages contain the same certificate and private key, but this security issue can be prevented by using a custom certificate (more details below).


Custom SSL Certificate

PEM certificates are supported (including self-signed, signed by a commercial certificate authority or similar).

  1. The private key has to be imported into the Dispatcher Paragon Payment System keystore.

  2. The certificate (containing the corresponding public key) has to be saved to the other Dispatcher Paragon components (Terminal Server, Spooler Controller, Dispatcher Paragon End User Interface).

Certificate changes will affect all payment webs (Cash Desk web, Dispatcher Paragon Payment System Wallet and Dispatcher Paragon Payment System Administration web) and REST API communication.

Step 1. Get the Certificate

Generate a self-signed certificate

Generate a new certificate and keys (you will be asked for the keystore password, which can be found in the SSL connector definition, file <PAYMENT_HOME >\conf\server.xml):

  1. Generate a self-signed certificate by running the following commands from the command line.

    cd <PAYMENT_HOME>\payment-conf
    <PAYMENT_HOME>\Java\bin\keytool -server -genkey -keyalg RSA -alias yps-tomcat -keystore keystore.jks -validity 365 -keysize 2048
    <PAYMENT_HOME>\Java\bin\keytool -server -exportcert -rfc -alias yps-tomcat -file YPSClient.crt -keystore keystore.jks

    You can use the keytool from any standard Java installation instead of the embedded Java from Dispatcher Paragon Payment System (use JRE 7 or higher).

    Option Validity is in days.

    Options like validity, alias and keysize can be changed.

  2. Make sure that the generated JKS and CRT files are in your <PAYMENT_HOME>\payment-conf directory.

  3. Make sure that the Common Name of your certificate is the same as the web address you will be using when connecting to your secure site.

The certificate Common Name (CN parameter) is typically composed of the host and domain name and will look like "www.yoursite.com" or "yoursite.com". SSL Server Certificates are specific to the Common Name that they have been issued to it at the host level.

Using an existing certificate

As Dispatcher Paragon Payment System uses a Java keystore, you usually need to convert certificates from common PEM files (.crt and .key) to a p12 file.

If you have a certificate and key in PEM format, the key is named YPSClient.key and the certificate YPSClient.crt. You can convert it using OpenSSL:

  1. Download and install OpenSSL from http://slproweb.com/products/Win32OpenSSL.html

  2. Open the command line and navigate to the dir with your KEY and CRT files.

  3. Run the following command:

    <OPENSSL_HOME>\bin\openssl pkcs12 -export -in YPSClient.crt -inkey YPSClient.key -out keystore.p12 -name "yps-tomcat"

  4. Import the P12 keystore into the Java keystore using the following commands (for more details, see section Generate a self-signed certificate above).

    cd <PAYMENT_HOME>\payment-conf
    <PAYMENT_HOME>\Java\bin\keytool -server -importkeystore -srckeystore keystore.p12 -destkeystore keystore.jks -srcstoretype pkcs12

  5. Here is an example of a successful keytool output

Entry for alias yps-tomcat successfully imported.
Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

Step 2. Configure Dispatcher Paragon Payment System

Edit <PAYMENT_HOME>\conf\server.xml, find the Connector block with the SSLEnabled="true" and:

  • change keystorePass to your new password.

  • If you changed the keytool -alias parameter in the previous steps, change keyAlias="yps-tomcat"

  • If you changed keytool -keystore parameter in the previous steps, change keystoreFile="${catalina.base}/payment-conf/keystore.jks"

Step 3. Configure Other Dispatcher Paragon Components

  1. Stop the Spooler Controller, Terminal Server and Dispatcher Paragon End User Interface services.

  2. Copy the new certificate YPSClient.crt (or replace an existing) into these directories:

    • <SAFEQ_HOME>\SPOC\terminalserver\Certificates

    • <SAFEQ_HOME>\SPOC\conf\certificates\

      This must be a single certificate in PEM format, not a truststore in PKCS#12 format. The certificate must belong to the issuer (CA) of the certificate used for Dispatcher Paragon Payment System.

  3. Copy <PAYMENT_HOME>\ysoft\keystore.jks to <SAFEQ_HOME>\SPOC\EUI\ui-conf\

  4. Start all services from the first step

Troubleshooting

You can get a list of imported certificates in the keystore using the command:

<PAYMENT_HOME>\Java\bin\keytool -server -list -keystore keystore.jks -storepass L1faMXVVpR

If you already have an alias present in the keystore, you can delete it using the following command:

<PAYMENT_HOME>\Java\bin\keytool -server -delete -alias yps_tomcat -keystore keystore.jks -storepass L1faMXVVpR