Stelo Technical Documents

SQDR Plus: Configuring SSL for Jetty (SQDR Control Center)

Last Update: 29 December 2022
Product: SQDR Plus
Version: 6.11 and later
Article ID: SQV00PL036

Abstract

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 automatically generated at service startup, 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 Microsoft SQL Server). That 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.

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

Contents:

• Prerequisites
• Duplicate the jetty.base directory
• 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 and restart the service
• 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 (CA)
• keytool (supplied with the JRE) should be in your PATH, or you should know the path to it
  e.g. C:\Program Files\StarQuest\jre\bin\keytool
• Be sure to save the password you supplied when creating the keystore, as it will be needed whenever you access the keystore.

The examples below illustrate using Windows; see the Linux section below for the equivalent Linux examples

Duplicate the jetty.base directory

Jetty files application binaries reside in jetty.home (e.g. C:\Program Files\Stelo\jetty) and configuration files in jetty.base (e.g. C:\Program Files\StarQuest\jetty.base.

We will duplicate jetty.base and modify its contents. For the rest of this document, jetty.base refers to the new location.

1. Copy the contents of jetty.base from the installation location (e.g. C:\Program Files\StarQuest\sqdrplus\jetty.base) to another location e.g. C:\ProgramData\StarQuest\sqdrplus\jetty\jetty.base:
2. Create a file named wrapper-local.conf in C:\ProgramData\StarQuest\sqdrplus\jetty containing the following:

wrapper.java.additional.5=-Djetty.base="C:\ProgramData\StarQuest\sqdrplus\jetty\jetty.base"

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 current parameter value; look for the line containing a reference to jetty.base.

wrapper-local.conf can also be used to override other parameters - for example, you can configure the SSL port with:

wrapper.java.additional.6=-Djetty.ssl.port=8444

3. Restart the SQDR Plus Jetty service and confirm that it starts OK; you will notice that the file jetty.base\etc\test-keystore.p12 is recreated every time the service is started.

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

1. Create a Keystore File and Generate a Key Pair. We suggest using the default location & filename for keystore (jetty.base\etc\keystore.p12)

keytool -genkeypair -keysize 2048 -keystore C:\ProgramData\StarQuest\sqdrplus\jetty\jetty.base\etc\keystore.p12 -alias jetty -keyalg RSA -sigalg SHA256withRSA

2. Generate a Certificate Signing Request (CSR):

keytool -certreq -alias jetty -keyalg RSA -file certreq.csr -keystore C:\ProgramData\StarQuest\sqdrplus\jetty\jetty.base\etc\keystore.p12 -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 and supply a 2 character country code.

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 or Edge, 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 C:\ProgramData\StarQuest\sqdrplus\jetty\jetty.base\etc\keystore.p12

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 and restart the service

1. Delete jetty.base\start.d\test-keystore.ini
2. Edit jetty.base\start.d\ssl.ini - uncomment jetty.sslContext.keyStorePassword and set it to the password.

jetty.sslContext.keyStorePassword=<pwd>
or
jetty.sslContext.keyStorePassword=OBF:<obscured password>

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

set MYPASS=mypassword
set UTIL=C:\Program Files\Stelo\jetty\lib\jetty-util-10.0.12.jar
java -cp "%UTIL%" org.eclipse.jetty.util.security.Password %MYPASS%

Use the output that begins with OBF: (including the OBF: prefix). Note that OBF passwords are not secure, just protected from casual observation.

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

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. In many cases, a Windows system that is a member of the Active Domain of the certificate server may already trust the CA.

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/Edge:
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
Click on Connection Secure
Click on More Information
Select View Certificate

Chrome:
Click on the padlock icon in the address bar
Click on Connection is Secure
Click on Certificate is Valid

Internet Explorer:
Click on the padlock icon to the right of the address bar
Select View Certificates

Edge:
Click on the padlock icon next to the address bar
Click on Connection is Secure
Click the certificate icon in the upper right corner (next to the X close-window icon)

Enforcing the Use of TLS 1.2

SQDR Plus now uses a recent version of Jetty that enforces the use of TLS 1.2 or later.

To verify that older protocols are not accepted, you can use the openssl command (e.g. on a Linux system:

$ openssl s_client -connect myhost.mydomain.com:8443 -tls1

Linux

Here are the typical commands on a Linux system. Perform these commands as user sqdr except as noted (root is only needed to restart the service).

• Copy the contents of jetty.base from the installation location

$ cd /opt/stelo/sqdrplus
$ tar cf - jetty.base | (cd /var/sqdrplus/jetty; tar xf -)

• Edit wrapper-local.conf:

$ vi /var/sqdrplus/jetty/wrapper-local.conf

and add the line:

wrapper.java.additional.5=-Djetty.base=/var/sqdrplus/jetty/jetty.base

• As root, restart jetty service:

# /etc/init.d/sqdr-jetty restart

• Confirm that a certificate store with the self-signed cert gets created in /var/sqdrplus/jetty/jetty.base/etc
• Create a Java keystore and CSR:

$ keytool -genkeypair -keysize 2048 -keystore /var/sqdrplus/jetty/jetty.base/etc/keystore.p12 -alias jetty -keyalg RSA -sigalg SHA256withRSA

$ keytool -certreq -alias jetty -keyalg RSA -file certreq.csr -keystore /var/sqdrplus/jetty/jetty.base/etc/keystore.p12 -ext san=dns:myhost.mydomain.com

• After submitting the CSR to the CA and retrieving the issued certificate, import the certificate into the keystore:

$ keytool -import -alias jetty -trustcacerts -file certnew.p7b -keystore /var/sqdrplus/jetty/jetty.base/etc/keystore.p12

• Configure jetty:

$  rm /var/sqdrplus/jetty/jetty.base/start.d/test-keystore.ini
$ vi /var/sqdrplus/jetty/jetty.base/start.d/jetty.base/start.d\ssl.ini

Uncomment jetty.sslContext.keyStorePassword and set it to the password.

• As root, restart the jetty service

# /etc/init.d/sqdr-jetty restart

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 10 Documentation: Configuring SSL/TLS Keystores

Public certificate authorities typically supply documentation for CSR creation and certificate installation for a Java-based keystore.