CA-signed certificate requirements

• The certificate must be signed by a certification authority trusted in your environment.

• Certificate (fields Common Name and Subject Alternative Name) must contain all network names (i.e. all hostnames, fully qualified domain names and IP addresses) used for connection to the YSoft SafeQ Payment System.

• For importing the certificate you need an appropriate format - Java Keystore (.jks file) containing the private key and whole certificate chain. The procedure below is simplified by creating a new keystore instead of reusing the existing one.

• Both the keystore and key itself need to be protected by a password

Configuring YSoft SafeQ Payment System to use secure communication channel

This section describes the way how to make the web connection secure using the CA-signed certificate.

1. Stop YSoft SafeQ Payment System service on YSoft SafeQ server.

2. Copy your key/certificate in the Java Keystore format to the server where YSoft SafeQ Payment System is installed.

3. Set following attributes in <payment_folder>\conf\server.xml file:

   keystoreFile = "absolute/path/to/your/keystore.jks"

   keystorePass = "keystore protecting password"

   keyPass = "key protecting password"

   By default, keyPass attribute has the same value as keystorePass. Set this attribute if the key and the keystore are protected using different passwords.

4. (OPTIONAL) To secure communication between Payment Gateway Plugin and Payment System by your certification authority, if a payment gateway is used, the path and protecting password to your truststore.jks file containing CA certificate need to be provided. The default password of the truststore is "bYOARJ741l" (without quotes). Add the new configuration properties truststore.path and truststore.password to the Payment System's configuration (<payment_folder>\ps-conf\environment-configuration.properties), see Security.
   

   In case you have important certificates in the truststore, you can use this same command to import your CA to the existing file. Just run this command inside the <payment_folder>\ps-conf directory.

   In this situation you also need to delete the default YSoft SafeQ Payment System certificates from the current truststore (if they are not replaced yet):

   keytool -delete -alias certalias -keystore truststore.jks

   keytool -delete -alias ca_root -keystore truststore.jks

   keytool -delete -alias ca -keystore truststore.jks

5. (OPTIONAL) Adding security to SMTP server. In order to establish secure communication between SMTP server and YSoft SafeQ Payment System (e.g. for email notifications), you also need to import your certificate to the default keystore located in <payment folder>\java\lib\security\ folder. For this, you can use the keytool again:

   keytool -import -keystore <<payment folder>\java\lib\security\cacerts> -file <absolute path to your certificate> -alias <a name for the certificate>

6. Start the YSoft SafeQ Payment System service on YSoft SafeQ server.

7. Verify that YSoft SafeQ Payment System is functional and uses your own certificate (open https://<payment_system_IP>:8443 in browser, click on the lock and view certificate button). In case you did not disable the automatic redirection to HTTPS, opening http://<payment_system_IP>:8080 address will be automatically redirected to https protocol.

Example of Tomcat HTTPS configuration

The configuration is stored in <payment_folder>\conf\server.xml (usually C:\SafeQ6\YPS\conf\server.xml)

The default, pre-installed private key is stored together with its corresponding certificate in <payment_folder>\ps-conf\keystore.jks file. Both, keystore and private key, are protected by the same password specified in configuration file with attribute keystorePass.

When client authentication is required (clientAuth attribute is set to true) then some attributes about truststore need to be added/modified in the "Connector" above:

• truststoreFile="<path-to-truststore>"

• truststorePass="*****"

• clientAuth="true"

The ciphers attribute contains list of cipher suites you want to support. Following configuration is recommended:

Terminal Server configuration

Communication between Terminal Server (client) and YSoft SafeQ Payment System (server) is performed via REST API, secured by default with a certificate provided by Y Soft. Terminal Server has a copy of server certificate exported from YSoft SafeQ Payment System and the thumbprint of these two files is validated.

After you change the certificate used by YSoft SafeQ Payment System, it is needed to make it trusted on the Terminal Server machine. There are two options:

a. Replace the YPSClient.crt file in <spoc_folder>\terminalserver\Certificates\ directory on Terminal Server machine by your yps.crt file (renamed to YPSClient.crt), containing only the server certificate (excluding your CA).

b. Import the your certificate authority to the machine with running Terminal Server (follow the guide Installing your Root CA to truststores of YSoft SafeQ machines - Windows Certificate Store in the System communication hardening) and set the following system property:

YSoft Payment Machine configuration

Communication between YSoft Payment Machine - YPM (client) and YSoft SafeQ Payment System - PS (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 PS 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.