Configuring SSL/TLS for Web interface

  This article will help you with the configuration of the secured connection (HTTPS) to the YSoft SafeQ web interface. This article consists of:

Tomcat 7 HTTPS configuration

 The configuration is stored in <SafeQCML>\tomcat\conf\server.xml for CML and <SafeQORS>\tomcat\conf\server.xml for ORS.

The recommended configuration as shown below is included in MU80 and higher. For older version, consider manual update.

Keep HTTP non-SSL/TLS port (default 80) as the first in XML. Installer requires HTTP port to be the first in definition. HTTPS should be the second.

server.xml - Default configuration
<Server port="-1" shutdown="SHUTDOWN">
 
<Connector port="80" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="443"
/>
 
<!-- Define a SSL/TLS Coyote HTTP/1.1 Connector on port 443 -->
<Connector port="443"
protocol="org.apache.coyote.http11.Http11NioProtocol"
maxHttpHeaderSize="8192"
maxThreads="200"
minSpareThreads="25"
enableLookups="false"
disableUploadTimeout="true"
acceptCount="100"
scheme="https"
sslProtocol="TLS"
secure="true"
SSLEnabled="true"
keystoreFile="${catalina.base}/conf/keystore.jks"
truststoreFile="${catalina.base}/conf/truststore.jks"
keystorePass="L1faMXVVpR"
truststorePass="bYOARJ741l"
URIEncoding="UTF-8"
clientAuth="false"
sslEnabledProtocols="TLSv1,TLSv1.1,TLSv1.2"
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_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA"
/>
</Server>

The default configuration uses JSSE SSL/TLS implementation. It is specified by the "Http11NioProtocol" in the server.xml configuration file. The JSSE implementation supports following keystore formats:

  • JKS

  • PKCS12 (Personal Information Exchange, typically with .p12 or .pfx extension)

Introduction

By default, SafeQ5 uses a built-in certificate generated by the Y Soft CA.

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

With the knowledge/access to the private key, it's possible to decrypt traffic and get administration access to the YSoft SafeQ5 API This may be a potential danger, as all YSoft SafeQ5 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/TLS Certificate customization

PEM certificates are supported (including self-signed, signed by commercial certificate authority or similar). The private key has to be imported into the YSoft SafeQ5 keystore


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

You can use keytool from YSoft Safeq5 located at <SafeQ5_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\java\bin\keytool" -genkey -keyalg RSA -alias sq5-tomcat -keystore keystore.jks -validity 365 -keysize 2048

or

"C:\Program Files (x86)\java\jre7\bin\keytool" -genkey -keyalg RSA -alias sq5-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 SafeQ5 keystore or truststore password, refer to <SafeQCML>\conf\server.xml and <SafeQORS>\tomcat\conf\server.xml configuration file:

Option 1.a Generate a CA-signed certificate

  1. Open command line and run the following keytool command to generate a key.

    keytool -genkeypair -keyalg RSA -keysize 2048 -alias sq5-tomcat -keystore sq5-keystore.jks -validity 365

    images/s/cs_CZ/7502/85262de2dab440f060366aadca149a69d65c1f59/_/images/icons/emoticons/lightbulb_on.png NOTE:  Validity is in days and can be customized, same as key alias and keysize.
    images/s/cs_CZ/7502/85262de2dab440f060366aadca149a69d65c1f59/_/images/icons/emoticons/lightbulb_on.png NOTE:  The Common Name (CN parameter) is typically composed of Host + Domain Name and will look like "www.yoursite.com" or "yoursite.com". SSL/TLS 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.

  2. In order to generate a certificate signing request (sq5-tomcat.csr file) to be sent to the Certification Authority, run the following keytool command:

  3. a) Send the created sq5-tomcat.csr file to the Certificate Authority. You will receive your signed certificate (sq5-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 SafeQ5 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 sq5-tomcat.csr -outfile sq5-tomcat.crt -ext BC=ca:false

    images/s/cs_CZ/7502/85262de2dab440f060366aadca149a69d65c1f59/_/images/icons/emoticons/lightbulb_on.png NOTE:  Validity is in days and can be customized.

  4. keytool -certreq -keystore sq5-tomcat.jks -alias sq5-tomcat -keyalg rsa -file sq5-tomcat.csr

    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 sq5-tomcat.crt file needs to contain certificates of all of them in specified order. The first certificate is the SQ5'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 >> sq5-tomcat.crt

  5. Import the signed certificate back to the YSoft SafeQ5 keystore. Use the following keytool command:

    keytool -import -keystore sq5-tomcat.jks -file sq5-tomcat.crt -alias sq5-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 and import it to the existing keystore

As YSoft Safeq5 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 sq5-tomcat.key and the certificate sq5-tomcat.crt. It can be done using OpenSSL:

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

images/s/cs_CZ/7502/85262de2dab440f060366aadca149a69d65c1f59/_/images/icons/emoticons/lightbulb_on.png 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 sq5-tomcat.pfx -alias sq5-tomcat -deststoretype JKS -destkeystore keystore.jks

Successful keytool output:

Entry for alias sq5-tomcat successfully imported.
Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

Option 1.c Use existing certificate in inappropriate format and create new keystore in Personal Information Exchange format


If the certificate is in the PEM format then it's required to convert it to the Personal Information Exchange ( .pfx or .p12) file.

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

Now, the keystore.p12 file can be used as a keystore in SafeQ5 server.xml configuration. For more details, see the Using Personal Information Exchange keystore format configuration example.

Option 1.d Use existing certificate in PEM format with APR SSL/TLS implementation

You can use PEM certificates directly by switching to the APR SSL/TLS implementation. For more details, see the Using PEM encoded certificates with APR SSL/TLS implementation configuration example.

Step 2. Configure YSoft SafeQ 5

2.a

Edit <SafeQCML>\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="sq5-tomcat"

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

  • if the password for private key is different to the keystorePass then configure also the following attribute:  keyPass="private key password"

2.b

  • Do the same for <SafeQORS>\tomcat\conf\server.xml

Step 3. Make your certificate trusted

Your new certificate or the whole certificate chain needs to be trusted. The certificate(s) needs to be imported into a new <SafeQCML>\tomcat\conf\truststore.jks and < SafeQORS > \tomcat\conf\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 sq5-tomcat.crt, intermediate.crt, root.crt you may use the following commands:

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

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

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

Alternative configuration examples

Using Personal Information Exchange keystore format (.pfx)

The Personal Information Exchange certificate format (PCKS12) is supported as certificate format by the default Http11NioProtocol. The .pfx keystore can be used instead of the default JKS keystore:

server.xml - with Personal Information Exchange keystore
<Server port="-1" shutdown="SHUTDOWN">
 
<Connector port="80" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="443"
/>
 
<!-- Define a SSL/TLS Coyote HTTP/1.1 Connector on port 443 using PFX keystore -->
<Connector port="443"
protocol="org.apache.coyote.http11.Http11NioProtocol"
maxHttpHeaderSize="8192"
maxThreads="200"
minSpareThreads="25"
enableLookups="false"
disableUploadTimeout="true"
acceptCount="100"
scheme="https"
sslProtocol="TLS"
secure="true"
SSLEnabled="true"
keystoreFile="${catalina.base}/conf/certificate-store.pfx"
truststoreFile="${catalina.base}/conf/truststore.jks"
keystorePass="CERTIFICATE_STORE_PASSWORD"
truststorePass="bYOARJ741l"
URIEncoding="UTF-8"
clientAuth="false"
sslEnabledProtocols="TLSv1,TLSv1.1,TLSv1.2"
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_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA"
/>
</Server>

Using PEM encoded certificates with APR SSL/TLS implementation

The default and recommended JSSE SSL/TLS implementation does not support PEM encoded certificates and keys directly. If your certificate is in PEM format, then you can convert it to the Personal Information Exchange format and use the converted certificate. It is also possible to use PEM certificate and key directly, by switching to APR SSL/TLS implementation by specifying the org.apache.coyote.http11.Http11AprProtocol connector in the configuration . This implementation supports only the PEM encoded certificates and keys.

Be aware that Http11AprProtocol connector has a different syntax than the default Http11NioProtocol.

server.xml - APR SSL implementation with PEM certificate
<Server port="-1" shutdown="SHUTDOWN">
 
<Connector port="80" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="443"
/>
 
<!-- Define a SSL/TLS Coyote HTTP/1.1 Connector on port 443 using APR SSL/TLS implementation -->
<Connector port="443"
protocol="org.apache.coyote.http11.Http11AprProtocol"
maxHttpHeaderSize="8192"
maxThreads="200"
minSpareThreads="25"
enableLookups="false"
disableUploadTimeout="true"
acceptCount="100"
scheme="https"
secure="true"
SSLEnabled="true"
SSLCertificateFile="${catalina.home}/conf/safeq-certificate.crt"
SSLCertificateKeyFile="${catalina.home}/conf/safeq-key.key"
SSLPassword="*****"
URIEncoding="UTF-8"
SSLVerifyClient="none"
SSLProtocol="TLSv1+TLSv1.1+TLSv1.2"
SSLCipherSuite="ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-ECDSA-CHACHA20-POLY1305,ECDHE-RSA-CHACHA20-POLY1305,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-SHA,ECDHE-RSA-AES256-SHA,ECDHE-ECDSA-AES128-SHA,ECDHE-ECDSA-AES256-SHA"
/>
</Server>

Required settings for YSoft SafeQ client

YSoft SafeQ Client communicates with YSoft SafeQ via web interface using embedded Internet Explorer. Generated SSL/TLS certificate needs to be installed on PC with SafeQ Client into Certificate store Trusted Root Certification Authorities in order to make SafeQ Client work properly. For detailed information see Problem: SafeQ client - Windows cannot validate certificate on troubleshooting page.

By default, the primary YSoft SafeQ IP address is used as the server name in all requests. Protocol and port for the connection is based on following settings (accessible from the web interface):

  • Use configuration value webServerProtocol to define whether to use the http or https protocol.

  • If webServerProtocol value is http, then YSoft SafeQ generates URL for client using webServerPort value (default: 80).

  • If webServerProtocol value is https, then YSoft SafeQ generates URL for client using webServerPortHTTPS value (default: 443).

 

Valid certificate is mandatory for HTTPS server. In case of invalid certificate client applications will display warning or it will refuse to display client window. Depends on security policies of the operating system

Custom host name SSL/TLS configuration

Optionally, the full YSoft SafeQ web URL (safeqWebBaseUrl) can be set. This value is used only by the YSoft SafeQ Client to configure a custom URL of YSoft SafeQ web interface to match the SSL/TLS certificate of YSoft SafeQ CML or ORS server.

  • This configuration property is not available from the web administration, it can be set only in the configuration files.

  • Individual SafeQ cluster nodes and ORS servers can have different values.

 

YSoft SafeQ CML Server

YSoft SafeQ ORS Server

Steps

  1. Install and configure YSoft SafeQ CML server (if not already installed)

  2. Open configuration file <safeq_folder>\conf\startup.conf

  3. Edit the safeqWebBaseUrl value
    (if not found, the property can be added, please see the startup.conf snippet bellow)

  4. Restart the YSoft SafeQ CML service

The safeqWebBaseUrl property can be set during YSoft SafeQ ORS server installation.

For detailed information see Installing YSoft SafeQ ORS.

 

startup.conf snippet
# Base URL (optional) of the YSoft SafeQ Web interface. If set, it is used used to access the YSoft SafeQ web interface from the YSoft SafeQ Client.
# Trailing slash is not allowed here. Valid examples: http://hostname.example.com, http://10.10.20.20:8080, https://secure.example.com.
safeqWebBaseUrl =

Troubleshooting

For more details in case of any problems please see: Troubleshooting HTTPS Web interface