Configuring Certificates for YSoft SafeQ Payment System

This guide provides information about the certificates used in YSoft SafeQ 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 (YSoft SafeQ Payment System Cash Desk, YSoft SafeQ Payment System Wallet and YSoft SafeQ Payment System Administration web) and REST API access.

Other YSoft SafeQ components (Terminal Server, Spooler Controller, YSoft SafeQ End User Interface) are configured to accept this certificate exclusively when communicating with the YSoft SafeQ 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:\SafeQ6\YPS.

With knowledge of/access to the private key, it is possible to decrypt traffic and gain administration access to the YSoft SafeQ Payment System API (including possibilities to make money transactions). This may be a potential danger as all YSoft SafeQ 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 an example of a default SSL certificate from YSoft SafeQ Payment System.

Owner: SURNAME=dza, [email protected], CN=YSoft payment system server certificate, OU=RnD, O=Y Soft Corporation, L=Brno, C=cz
Issuer: SURNAME=DZA, [email protected], CN=YSoft RnD CA, OU=RnD, O=Y Soft 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 a commercial certificate authority or similar).

  1. The private key has to be imported into the YSoft SafeQ Payment System keystore.

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

Certificate changes will affect all payment webs (Cash Desk web, YSoft SafeQ Payment System Wallet and YSoft SafeQ 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 YSoft SafeQ 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 YSoft SafeQ 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 YSoft SafeQ 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 YSoft SafeQ Components

  1. Stop the Spooler Controller, Terminal Server and YSoft SafeQ 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 YSoft SafeQ 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