Stelo Technical Documents

SQDR Plus: Configuring SSL for Jetty (SQDR Control Center)
for SQDR Plus 5.x

Last Update: 8 February 2018
Product: SQDR Plus
Version: 4.50 and later
Article ID: SQV00PL036A

Abstract

This archived technical doc describes configuring SSL for Jetty for SQDR Plus 5.x; see SQDR Plus: Configuring SSL for Jetty for configuring SSL in SQDR Plus 6.x & later.

SQDR uses the Java-based open source project Jetty to implement a web server (the SQDR Control Center) used for configuring and controlling SQDR Plus. By default, the SQDR Control Center uses a self-signed certificate supplied by the jetty project, stored in a Java keystore, for SSL (Secure Socket Layer) connections.

This technical document describes how to configure the SQDR Control Center to use a third party SSL certificate, using either an internal or a public certificate authority (CA).

Note: SQDR also supports SSL communications between SQDR and supported source databases (e.g. IBM DB2 for i and MySQL). This function is unrelated to the SSL communications described in this document, which encrypts the conversations between the SQDR Control Center and the administrator's web browser. You can use the same Java keystore for both purposes, but this document will demonstrate the use of a separate keystore.

Contents:

• Prerequisites
• Create a Java keystore and a certificate signing request (CSR)
• Submit the CSR to a Certificate Authority
• CA task: Generate and export the certificate (example: Microsoft Windows Certificate Services)
• Import the certificate chain into the keystore
• Configure jetty to use a local jetty-ssl.xml configuration file
• Configure jetty-ssl.xml to use the new Java keystore
• Configure the browser to trust the Certificate Authority
• Test the certificate with a browser
• Enforcing the use of TLS 1.2
• Issues
• References

Solution

Prerequisites

• Access to a Certificate authority
• keytool (supplied with the JRE) should be in your PATH, or you should know the path to it
  e.g. C:\Program Files\Java\jre1.8.0_161\bin\keytool
• Be sure to save the password you supplied when creating the keystore, as it will be needed whenever you access the keystore.

Create a Java keystore and a certificate signing request (CSR)

Create a Keystore File and Generate a Key Pair:

keytool -genkeypair -keysize 2048 -keystore keystore.jks -alias jetty -keyalg RSA -sigalg SHA256withRSA

Generate a Certificate Signing Request (CSR):

keytool -certreq -alias jetty -keyalg RSA -file certreq.csr -keystore keystore.jks -ext san=dns:myhost.mydomain.com

When prompted, supply the fully qualified host name of the server e.g. myhost.mydomain.com at the "first and last name" prompt.

You will also be prompted to enter a keystore password; save this password as it will be needed again later.

Submit the CSR to a Certificate Authority

If you are using a public Certificate Authority, follow the vendor's instructions for submitting the CSR and retrieving the certificate chain. in Base 64 encoded format; skip the next step.

Generate and export the certificate (example: Microsoft Windows Certificate Services)

If you are using an internal Certificate Authority, the CA administrator will generate a certificate based on the CSR. This example shows the creation of a certificate using Windows Certificate Services. Your CA may also be based on other technologies such as OpenSSL; the goal is to obtain a Base 64 encoded certificate that can be imported into jetty's Java keystore and (if necessary) imported into the end user's browser.

1. Using Internet Explorer, browse to https://mycertaut.mydomain.com/certsrv
2. logon with your domain credentials
3. Select Request a certificate
4. Select Submit an advanced certificate request.
5. Select Submit a certificate request by using a base-64-encoded CMC or PKCS #10 file, or submit a renewal request by using a base-64-encoded PKCS #7 file.
6. Past in the CSR (base-64-encoded certificate request)
7. Select Web Server for Certificate template
8. Click Submit
9. You will see this warning; respond yes.

This website is attempting to perform a digital certificate operation on our behalf
Respond yes to allow this operation

10. Select Download certificate chain as Base 64 encoded
11. Save the file as certnew.p7b

Import the certificate chain into the keystore

keytool -import -alias jetty -trustcacerts -file certnew.p7b -keystore keystore.jks

If you are using a private CA, you may see the following warning; respond with yes.

... is not trusted. Install reply anyway? [no]: yes

Configure jetty to use a local jetty-ssl.xml configuration file

The SQDR Jetty Service is installed under Program Files\StarQuest\sqdrplus\jetty (i.e. the Jetty “home directory”) and the default configuration files are placed in the etc subfolder.

By default, jetty uses the file Program Files\StarQuest\sqdrplus\jetty\etc\jetty-ssl.xml for SSL configuration. This file should not be modified, as it will be replaced by future updates to SQDR Plus.

Instead, override the use of this file:

1. Copy jetty-ssl.xml to another location e.g. C:\ProgramData\StarQuest\sqdrplus\jetty.
2. Create a file named wrapper-local.conf in C:\ProgramData\StarQuest\sqdrplus\jetty containing the following:

wrapper.app.parameter.2=C:/ProgramData/StarQuest/sqdrplus/jetty/jetty-ssl.xml

Note: the parameter number may change in future versions of SQDR Plus. Examine the file Program Files\StarQuest\sqdrplus\jetty\wrapper\conf\wrapper.conf to verify the curent parameter value; look for the line containing a reference to jetty-ssl.xml.

Configure jetty-ssl.xml to use the new Java keystore

Use a text editor to modify your local copy of jetty-ssl.xml to use the new Java keystore, supplying the full path of the keystore file and the keystore password, and restart the SQDR Jetty service.

You can either supply the password in plain text (e.g. for initial testing), or obfuscate it with the Jetty password utility:

set UTIL=C:\Program Files\StarQuest\sqdrplus\jetty\lib\jetty-util-8.1.5.v20120716.jar
java -cp "%UTIL%" org.eclipse.jetty.util.security.Password mypassword

Use the output that begins with OBF: (including the OBF: prefix) for the password parameter in jetty-ssl.xml.

Sample snippet:

<Set name="KeyStore">C:\ProgramData\StarQuest\SSL\keystore.jks</Set>
<Set name="KeyStorePassword">OBF:1ym72ym31u9j2xtt1xtp1u9z2ymb1ym7</Set>

On Windows, you can use either forward or back slashes in the KeyStore filename.

Configure the browser to trust the Certificate Authority

Skip this step if you are using a public certificate authority or an internal certificate authority for which your browser has already been configured.

If you are using an internal CA, you may need to configure the browser to trust it by importing the certificate chain:

Chrome:
.../Settings/Advanced/Manage certificates/Trusted Root Certificate Authorities/Import...

Firefox:
Tools/Options/Advanced/Certificates/View Certificates/Authorities/Import...

Internet Explorer:
Use MMC and the Certificates snap-in to configure the Windows certificate store (My user Account (current user)/Trusted Root Certificate Authorities)

Test the certificate with a browser

Point a browser at https://myhost.mydomain.com:8443/SQDRManager

Examine the certificate in the browser:

Firefox:
Click on the padlock icon in the address bar
then the > symbol to the right of the displayed system name
then More Information
View Certificate

Chrome:
.../More Tools/Developer Tools
select Security in the right panel

Internet Explorer:
Click on the padlock icon next to the address bar
View Certificates

Enforcing the Use of TLS 1.2

The use of TLS 1.2 and pro-active disabling of older protocols such TLS 1.0 and 1.1 is recommended when using SSL encryption.

To disable the use of older protocols such as TLS 1.0 and 1.1, either:

• Edit jre/lib/security/java.security in the JRE:

jdk.tls.disabledAlgorithms=SSLv3, RC4, MD5withRSA, DH keySize < 1024, EC keySize < 224, DES40_CBC, RC4_40,, TLSv1, TLSv1.1

You may need to repeat this change after future JRE updates.

OR

• Modify your local copy of jetty-ssl.xml (created as described above) by adding the following to the New id="sslContextFactory" section:

<Set name="ExcludeProtocols">
  <Array type="java.lang.String">
    <Item>SSLv2Hello</Item>
    <Item>TLSv1</Item>
    <Item>TLSv1.1</Item>
  </Array>
</Set>

To verify the older protocols have been disabled, look for this message in the jetty wrapper.log (C:\ProgramData\StarQuest\sqdrplus\jetty\logs\wrapper.log):

INFO:oejus.SslContextFactory:Enabled Protocols [TLSv1.2] of [SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2]

Issues

Jetty wrapper log

If you experience problems starting jetty after configuration changes, examine the jetty wrapper log \ProgramData\StarQuest\sqdrplus\jetty\logs\wrapper.log.

Untrusted Certificate Authority

The following are typical messages you may see if you need to add the CA certificate to the browser's list of certificate authorities:

SEC_ERROR_UNKNOWN_ISSUER
ERR_CERT_AUTHORITY_INVALID
The certificate is not trusted because it is self-signed.
the certificate provided was issued by a certificate authority that is not known by the browser.

Weak signature algorithm (SHA-1)

Recent versions of Chrome may refuse to trust the certificate with this error:

NET::ERR_CERT_WEAK_SIGNATURE_ALGORITHM
The server presented a certificate signed using a weak signature algorithm (such as SHA-1).

This was encountered when testing with a certificate issued by Windows 2012R2 Certificate Services.

See the following for instructions on upgrading Windows Certificate Services to use SHA2:

Migrating your Certification Authority Hashing Algorithm from SHA1 to SHA2

Migrating a Certification Authority Key from a Cryptographic Service Provider (CSP) to a Key Storage Provider (KSP)

References

Jetty/Howto/Configure SSL

Jetty/Howto/Secure Passwords

Public certificate authorities typically document CSR creation and certificate installation for a Java-based keystore. For example:

Thawte:
Generate a Certificate Signing Request (CSR) for Jetty Java HTTP Servlet Web Server
Import Thawte SSL Certificate into Jetty Java HTTP Servlet Web Server

Comodo:
CSR Generation: Java Based Web Servers (Tomcat) using keytool
Certificate Installation: Java Based Web Servers (Tomcat) using keytool