Configuring Certificates for Dispatcher Paragon Payment System

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

Introduction

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

Other SafeQ components (Terminal Server, Spooler controller, YSoft 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 the knowledge/access to the private key, it is possible to decrypt traffic and get 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).

Here is example of default SSL certificate from Dispatcher Paragon Payment System. 

Owner: SURNAME=dza, EMAILADDRESS=info@ysoft.com, CN=YSoft payment system server certificate, OU=RnD, O=Konica Minolta Corporation, L=Brno, C=cz
Issuer: SURNAME=DZA, EMAILADDRESS=info@ysoft.com, CN=YSoft RnD CA, OU=RnD, O=Konica Minolta Corporation, L=Brno, C=cz
Serial number: 8
Valid from: Tue Feb 04 14:30:21 CET 2014 until: Thu Dec 17 15:15:17 CET 2099 
Certificate fingerprints:
                MD5:  54:11:E0:7A:7F:A5:E9:D6:BB:42:2D:39:B4:0B:EB:34
                SHA1: 06:12:14:1D:4F:61:F6:22:55:09:DD:0F:BD:60:F2:62:B7:00:41:FC
                SHA256: C8:60:69:27:51:B9:53:34:8E:AF:EA:48:27:54:B4:58:54:05:8A:C5:80:68:4F:3A:B9:F4:96:1F:AF:A1:87:0C
                Signature algorithm name: SHA512withRSA
                Version: 3

Custom SSL Certificate

PEM certificates are supported (including self-signed, signed by 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 SafeQ components (Terminal Server, Spooler controller, YSoft end user interface).

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

Step 1. Get the certificate

Generate 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 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 keytool from any standard Java installation instead of 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 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.

Ceriticate Common Name (CN parameter) is typically composed of 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 at the Host level.

Use existing certificate

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

Suppose that you have a certificate and key in PEM format. The key is named YPSClient.key and the certificate YPSClient.crt. You can convert it by OpenSSL:

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

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

  3. Run following command.

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

  4. Import P12 keystore into Java keystore by following commands (for more detail, see chapter Generateself-signedcertificate)

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

  5. Here is example of 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 Connector block with the SSLEnabled="true" and change:

  • keystorePass to your new password

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

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

Step 3. Configure other SafeQ components

  1. Stop Spooler controller, Terminal Server and YSoft end user interface services

  2. Copy new certificate YPSClient.crt (or replace 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 by command:

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

In case that you already have alias present in keystore you can delete it by following command:

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