Configuring SSL/TLS for YSoft SafeQ Payment System

By default, YSoft SafeQ Payment System is automatically redirecting all HTTP requests to encrypted HTTPS connection. In order to ensure secure connection, you need to use certificate trusted in your environment.

This guide will help you with the configuration of the secured connection (HTTPS) to the YSoft SafeQ Payment System, using a CA-signed certificate.

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.

  In case your key/certificate is in a different format than Java Keystore, convert it following the Conversions between different keystores and certificate types.

  
  

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

Configure custom certificate in YSoft SafeQ Payment System

This section describes how to secure the web connection using a CA-signed certificate. The procedure simplifies configuration by creating a new keystore rather than importing the new certificate into the existing one.

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:

   XML

   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 keyPass attribute only if the key and the keystore are protected using different passwords.

   
   

   If you prefer to reuse the existing keystore, the command for import of your new certificate would be as follows:
   <payment_folder>\Java\bin\keytool -importkeystore -srckeystore <path_to_java_keystore_with_new_certificate> -srcstorepass <keystore_protecting_password> -srckeypass <key_protecting_password> -srcalias <key_alias> -destkeystore <payment_folder>\ps-conf\keystore.jks -deststorepass <keystorePass_from_server.xml> -destkeypass <keyPass_from_server.xml>

   Keystore default password: L1faMXVVpR
   Expected output: Import command completed: 1 entries successfully imported, 0 entries failed or cancelled

   
   

4. If you are using or plan to use Payment Gateway Plugin, import new certificate to truststore of Payment System

   • default location: <payment_folder>\ps-conf\truststore.jks

   • default password: bYOARJ741l

     custom location and password can be set in <payment_folder>\ps-conf\environment-configuration.properties, parameters truststore.path and truststore.password, see Security

     
     

   • command for import:
     

     Bash

     <payment_folder>\Java\bin\keytool.exe -import -alias <unique_text_eg_customcertdatetime> -file <path_to_your_new_certificate.crt> -keystore <payment_folder>\ps-conf\truststore.jks
     

     
     

   • command expected output:
     Import command completed: 1 entries successfully imported, 0 entries failed or cancelled

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 the <payment_folder>\conf\server.xml file.

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" useBodyEncodingForURI="true" />
 
<Connector port="8443"
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    maxThreads="200"
    scheme="https"
    secure="true"
    SSLEnabled="true"
    keystoreFile="${catalina.base}/ps-conf/keystore.jks"
    keystorePass="*****"
    clientAuth="false"
    sslProtocol="TLS"
    sslEnabledProtocols="TLSv1.2+TLSv1.3"
    ciphers="..."
    useBodyEncodingForURI="true"
/>

The default, pre-installed private key is stored together with its corresponding certificate in the <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:

ciphers="TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_DHE_DSS_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_DSS_WITH_AES_128_GCM_SHA256"

Configure other YSoft SafeQ components to accept the new Payment System certificate

Communication between YSoft SafeQ Payment System (acting as server) and other components (EUI, SPOC, TS - acting as client) is secured by default with a Y Soft-provided certificate. After the change of Payment System certificate, you must make it trusted in the other components.

1. Import new certificate to truststore of End User Interfacedefault location: <spoc_folder>\EUI\ui-conf\truststore.jks default password: <empty>command for import: <spoc_folder>\Java\bin\keytool.exe -import -alias <unique_text_eg_customcertdatetime> -file <path_to_your_new_certificate.crt> -keystore <spoc_folder>\EUI\ui-conf\truststore.jks command expected output:Import command completed: 1 entries successfully imported, 0 entries failed or cancelled

2. Import new certificate to truststore of Spooler Controllerdefault location: <spoc_folder>\conf\ssl-truststore default password: <empty>command for import: <spoc_folder>\Java\bin\keytool.exe -import -alias <unique_text_eg_customcertdatetime> -file <path_to_your_new_certificate.crt> -keystore <spoc_folder>\conf\ssl-truststore command expected output:Import command completed: 1 entries successfully imported, 0 entries failed or cancelled

3. Make new certificate trusted in Terminal ServerCommunication between the Terminal Server (client) and the YSoft SafeQ Payment System (server) uses a REST API, secured by default with a Y Soft–provided certificate. The Terminal Server stores a copy of the server certificate, and its thumbprint is validated.After the change of Payment System certificate, you must make it trusted on the Terminal Server. Two options are available:Replace certificate fileReplace the YPSClient.crt file in <spoc_folder>\terminalserver\Certificates\ with your yps.crt (renamed to YPSClient.crt), containing only the server certificate (excluding the CA).Import CAImport your certificate authority to the Terminal Server (see Installing your Root CA to truststores of YSoft SafeQ machines – Windows Certificate Store in (6.0.116) System communication hardening) and set the following system property:ypsServerCertificateValidationType = STANDARD

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.

You have to set the following configuration option in the <payment_folder>\ps-conf\environment-configuration.properties configuration file:

spm.deprecated.protocol.support = true

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

-- 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';

Troubleshooting

You can get a list of imported certificates in the keystore or truststore using -list command, example:

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

If you already have an alias present in the keystore or truststore and your import command fails on duplicity, you can delete it using command similar to this:

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