Page content

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

Introduction

By default, YSoft Payment System uses a built-in certificate generated by the Y Soft CA and accepts secure SSL/TLS connections only. This applies to both web interfaces (Cashdesk, Wallet and Payment administration) and API access.

YSoft SafeQ CML, ORS and Terminal Server are configured to accept this certificate exclusively when communicating with the YSoft Payment System server.

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

With the knowledge/access to the private key, it's possible to decrypt traffic and get administration access to the YSoft Payment System API (including possibilities to make money transactions). This may be a potential danger, as all YSoft 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).

Default SSL Certificate

Owner: SURNAME=dza, EMAILADDRESS=info@ysoft.com, CN=YSoft payment system server certificate, OU=RnD, O=Y Soft Corporation, L=Brno, C=cz

Issuer: SURNAME=DZA, EMAILADDRESS=info@ysoft.com, 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

SSL Certificate customization

PEM certificates are supported (including self-signed, signed by commercial certificate authority or similar). Summary of the required actions:

The private key has to be imported into the YSoft Payment System keystore
The certificate in PEM has to be saved to the CML, ORS (if used) and Terminal Server with the whole certificate chain if applicable.

Certificate change will affect both Cashdesk and Payment administration web interfaces and API communication.

All commands mentioned in this document are using keytool, which is part of standard Java JRE installation.

You can use keytool from YSoft Payment System located at <payment_system_folder>\Java\bin, or you can find this tool in the standart Java JRE bin folder. In case Java directory is not configured in your system variables, you will have to specify the path to keytool. The sample command then may look like this:

"C:\SafeQ5\PaymentSystem\Java\bin\keytool" -genkey -keyalg RSA -alias yps-tomcat -keystore keystore.jks -validity 365 -keysize 2048

or

"C:\Program Files (x86)\Java\jre7\bin\keytool" -genkey -keyalg RSA -alias yps-tomcat -keystore keystore.jks -validity 365 -keysize 2048

Step 1. Get the certificate

You can either generate a self signed certificate or obtain a certificate signed by a Certification authority. If prompted for a default YSoft Payment System keystore or truststore password, refer to <payment_system_folder>\conf\server.xml configuration file:

Option 1.a Generate a CA-signed certificate

Open command line and run the following keytool command to generate a key.
keytool -genkeypair -keyalg RSA -keysize 2048 -alias yps-tomcat -keystore yps-keystore.jks -validity 365
NOTE: Validity is in days and can be customized, same as key alias and keysize.
NOTE: The Common Name (CN parameter) is typically composed of Host + 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. The Common Name must be the same as the Web address you will be accessing when connecting to a secure site.
In case you do not need a CA-signed certificate and the self-signed one is enough for you, do not perform other steps in this section.
In order to generate a certificate signing request (yps-tomcat.csr file) to be sent to the Certification Authority, run the following keytool command:
keytool -certreq -keystore yps-tomcat.jks -alias yps-tomcat -keyalg rsa -file yps-tomcat.csr
a) Send the created yps-tomcat.csr file to the Certificate Authority. You will receive your signed certificate (yps-tomcat.crt), along with the certificate of this Authority (root.crt). In case only one file (containing all certificates needed) is received, skip the next step.
b) Or sign your YSoft Payment System certificate with your Certification Authority (let's name it root.jks file, in case it was created using keytool) using following command:
keytool -gencert -rfc -keystore root.jks -alias root -validity 365 -infile yps-tomcat.csr -outfile yps-tomcat.crt -ext BC=ca:false
NOTE: Validity is in days and can be customized.
Concatenate the signed certificate and CA certificates in PEM format into one file. In case you have longer certificate chain containing more than one Certification Authority, the yps-tomcat.crt file needs to contain certificates of all of them in specified order. The first certificate is the payment's one. Each following certificate belongs to the authority who signed the previous certificate directly. The last one belongs to the Root CA.
You can use e.g. a text editor or the following command (in case of longer chain write all the needed files in the above specified order):
type root.crt >> yps-tomcat.crt
Import the signed certificate back to the YSoft Payment System keystore. Use the following keytool command:
keytool -import -keystore yps-tomcat.jks -file yps-tomcat.crt -alias yps-tomcat
Write "yes" to confirm you want to import these certificates. If import was successful, the following message should appear:
Certificate reply was installed in keystore

Option 1.b Use existing certificate in inappropriate format

As YSoft Payment System uses Java keystore, it's usually required to convert certificates from the common PEM files (.crt and .key) to the Personal Information Exchange (.pfx or .p12) file.

Suppose you have a certificate and key in PEM format. The key is named yps-tomcat.key and the certificate yps-tomcat.crt. It can be done using OpenSSL:

openssl pkcs12 -export -in yps-tomcat.crt -inkey yps-tomcat.key -out keystore.p12 -name "yps-tomcat.pfx"

NOTE: OpenSSL can be downloaded and installed from following link: http://slproweb.com/products/Win32OpenSSL.html. You can run command openssl from installation bin folder or add it to system Path system environment variables.

Import Personal Information Exchange (.pfx or .p12) file into Java keystore (.jks file):

keytool -importkeystore -srcstoretype pkcs12 -srckeystore yps-tomcat.pfx -alias yps-tomcat -deststoretype JKS -destkeystore keystore.jks

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 Payment System

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

if you created a new keystore then change keystorePass with your new password
if you changed keytool -alias parameter in previous step then change keyAlias="yps-tomcat"
if you changed keytool -keystore parameter in previous step then change keystoreFile="${catalina.base}/ysoft/keystore.jks"
if the password for private key is different to the keystorePass then configure also the following attribute: keyPass="private key password"

Step 3. Make your certificate trusted in YSoft Payment System

Your new certificate or the whole certificate chain needs to be trusted in YSoft Payment System, especially in the case of using a Payment Gateway (such as PayPal). The certificate(s) needs to be imported into a new <payment_system_folder>\ysoft\truststore.jks store, the old one should be deleted. Provided that you have exported all certificates from the current certificate chain (e.g. hostname certificate signed by Intermediate Certification Authority which is signed by a Root Certification Authority) into yps-tomcat.crt, intermediate.crt, root.crt you may use the following commands:

keytool -import -keystore truststore.jks -file yps-tomcat.crt -alias yps-tomcat
keytool -import -keystore truststore.jks -file intermediate.crt -alias yps-tomcat-ca
keytool -import -keystore truststore.jks -file root.crt -alias yps-tomcat-root

To apply the new truststore, some configuration properties need to added into the payment's configuration <payment_system_folder>\ps-conf\environment-configuration.properties. See Security .

For later use the above CRT certificates (PEM format) should be concatenated into yps-tomcat.crt with some text editor or with the following commands in the same order:

type intermediate.crt >> yps-tomcat.crt
type root.crt >> yps-tomcat.crt

Step 4. Configure CML, ORS, Terminal Server

Stop Payment System, CML, ORS and TS services
Rename the yps-tomcat.crt file to YPSClient.crt.
Copy new certificate into CML/ORS and TS (replace existing files):
```
copy YPSClient.crt "<terminal_server_folder>\Certificates\YPSClient.crt"
copy YPSClient.crt "<safeq_home>\conf\certificates\YPSClient.crt"
```
NOTE: 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 Payment System.
Start Payment System, CML, ORS and TS services

Troubleshooting

To display a list of imported certificates in the current keystore use the following command:

keytool -list -keystore keystore.jks

In case that an alias is already present in the keystore delete it with following command:

keytool -delete -alias yps_tomcat -keystore keystore.jks

The password to the default keystore can be found in the <payment_system_folder>\conf\server.xml file, in the keystorePass attribute.

PayPal integration

In case your security certificate is valid only for the hostname of the server. You might need to reconfigure PayPal integration to use only hostname while contacting the different web services. Start with the following web configuration:

images/download/attachments/36373961/image2018-1-10_15_56_30.png

In case additional links must be changed please refer to "Advanced configuration of PayPal Gateway Plugin" article, specifically to the following attributes:

paypal.paymentSystemUrl
paypal.returnUrlPrefix

YSoft Payment Machine SSL configuration

Communication between YSoft Payment Machine - YPM (client) and YSoft Payment System - YPS (server) is performed via TCP on ports 4197 and 4199. By default a YPM communicates over TLS protocol, the only supported version is TLSv1, it also supports only the following two cipher suites TLS_DHE_RSA_WITH_AES_128_CBC_SHA and TLS_DHE_RSA_WITH_AES_256_CBC_SHA.

Default configuration of YPM and YPS uses the protocol TLSv1 and the cipher suite TLS_DHE_RSA_WITH_AES_128_CBC_SHA. To support the stronger cipher suite TLS_DHE_RSA_WITH_AES_256_CBC_SHA the Java Cryptography Extension needs to be placed into <payment-folder>/Java/lib/security . Before the extension is used, a jurisdiction of a customer's country needs to be checked if the stronger cipher suite is allowed.

To change the current configuration, the following DB queries needs to be run:

YPM security configuration

-- enable/disable SSL communication
-- 'false' to disable SSL - NOT RECOMMENDED
-- default value is 'true'
update configuration set value = 'true' where name = 'spm.sslEnabled';
 
-- change SSL request protocol
-- default and only supported by YPM is 'TLSv1'
update configuration set value = 'TLSv1' where name = 'spm.sslRequestProtocol';
 
-- change SSL cipher suites
-- to use the stronger cipher suite, the extension needs to be installed
-- default and only supported by YPM are '
update configuration set value = 'TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA' where name = 'spm.sslCiphersWhiteList';