Configuring TLS / SSL (Java 11 and forward)

Creating a new Wildcard TLS / SSL Certificate

Do not use these instructions with a server running Java 8 or less.

Create a PCKS 12 Keystore

Create a directory and keystore to hold the self signed certificate.

Linux / UNIX

mkdir /genesis/ssl

cd /genesis/ssl

keytool -genkey -alias tomcat -keystore genesis.p12 -storetype PKCS12 -keyalg RSA -storepass sch00lisc00l

Windows

d:

mkdir \genesis\ssl

cd \genesis\ssl

keytool -genkey -alias tomcat -keystore genesis.p12 -storetype PKCS12 -keyalg RSA -storepass sch00lisc00l

Creating a certificate with Subject Alternative Names (alternate domain names)

Additional domain names can be added to the certificate In addition to the domain name that is specified in the What is your first and last name? section below.

To add 1 domain, Add the -ext SAN=dns:fqdn parameter to the end of the keytool command above.

To add more than 1 domain:  -ext SAN=dns:fqdn1,dns:fqdn2.....

keytool -genkey -alias tomcat -keystore genesis.p12 -storetype PKCS12 -keyalg RSA -storepass sch00lisc00l -ext SAN=dns:staff.mydomain.com,dns:portal.mydomain.com

The tool will ask several questions, the following table shows appropriate answers:

It's important that the first and last name field contain the domain name of the server.

Configure Apache Tomcat to use the SSL Certificate

Hey - Next, we must tell Tomcat to use this certificate store (and self signed certificate).

• Stop tomcat.
• Edit the /usr/tomcat/conf/server.xml (or c:\tomcat\conf\server.xml) file.
• Look for the line <Service name="Catalina">
• Add this block of xml after the above line (replace the bold text with the appropriate values):

<Connector port="443"

              enableLookups="false"

              connectionTimeout="20000" scheme="https"

              sslProtocol="TLS" secure="true" SSLEnabled="true"

              keystoreFile="c:/genesis/ssl/genesis.p12"

              keystorePass="sch00lisc00l"   

                         sslEnabledProtocols="all,-SSLv2Hello,-TLSv1,-TLSv1.1" />

• If you want Genesis to listen on only SSL; then comment out all of the other connector XML blocks.
• Start Tomcat.

Test the self signed certificate

Using any web browser; Navigate to genesis using the HTTPS protocol (for example: https://www.genesisedu.com/genesis)
Because this is a self signed certificate, you should receive a warning.
Click the Yes (or OK) button to continue.
  

Genesis is now configured to work with SSL. In this configuration, every time a user logs into Genesis; they will be presented with the above dialog box. To eliminate this dialog box; the self signed certificate will need to be promoted to a signed certificate.

Upgrading to a signed certificate

A signed SSL Certificates is purchased from a certificate authority such as http://www.verisign.com, http://www.thawte.com, or http://www.godaddy.com. The prices range vastly between the different authorities. A Certificate is purchased for a time period usually from 1 to 5 years.  

Create a CSR (Certificate Signing Request)

Go to the d:\genesis\ssl or /genesis/ssl directory and run this command:

keytool -certreq -alias tomcat -keyalg RSA -sigalg SHA256withRSA -file certreq.csr -keystore genesis.p12

You will be asked for the password that you entered earlier. Once entered; a file called *certreq.csr *will be created. This is an ordinary text file. When applying for a certificate, the certificate authority will ask you for the contents of this file. Some authorities will let you attach the file as an e-mail; others will ask you to copy and paste the contents of the file into a web form.
You will also be asked by your certificate authority; what type of web server will this certificate be used on. Make sure that you answer anything with the word Tomcat in it. It is important that you do not answer Apache. Tomcat is not Apache; but Tomcat is made by Apache (The same people that make the Apache Web Server).
 You now have the required data to purchase a certificate. Once the certificate is purchased; continue to the next step.

Installing the signed certificate

Make a copy of the genesis.jks file before doing proceeding.

Obtain and install the chain (or root) and intermediary certificates.

Some vendors will require that a intermediary or root certificate be installed before installing the certificate itself.   These instructions vary from vendor to vendor.   If your vendor has given you these files ; the process to import them is:

keytool -import -alias inter1 -keystore genesis.p12 -trustcacerts -file gd_bundler.crt

For each certificate file provided (except the actual signed certificiate); use a different alias; and of course supply the correct filename in the -file parameter.

Install your new certificate

Finally; install the actual signed certificate

keytool -import -alias tomcat -keystore /genesis/genesis.p12 -trustcacerts -file certificate.txt

Start or restart Apache Tomcat.

Updating an expired certificate

When your certificate expires; you will need to install a new certificate with a new expiration date. You will need to obtain this certificate from the Certificate Authority that you purchased your original certificate from. 

Stop Tomcat.
Make a backup the genesis.jks file before proceeding

Install the upgraded certificate with this command (run this from the d:\genesis\ssl or /genesis/ssl directory)

keytool -import -alias tomcat -keystore genesis.p12 -trustcacerts -file certificateX.crt

Start Tomcat.

Using a certificate from an IIS Server

It is possible with Apache Tomcat 6 and 7 running on Java 1.6.0_12 or better to export an existing certificate from a Microsoft IIS server*.  * The certificate should be exported to a *.pfx file.   During the export process it will ask you to choose a password for the .pfx file.  Be sure to keep a note of it.   Place the .pfx file in the d:\genesis\ssl (or /genesis/ssl) directory on the Genesis server.

Open the server.xml file; and alter the SSL connector section to look something like this:

<Connector port="443"

              enableLookups="false"

              connectionTimeout="20000" scheme="https"

              sslProtocol="TLS" secure="true" SSLEnabled="true"

              keystoreFile="d:/genesis/ssl/myisscert.pfx"

              keystorePass="sch00lisc00l"

              keystoreType="pkcs12" />

Note: Be sure to correctly enter the keystore password or you may encounter an error that looks like "Given final block not properly padded'. You will see this error log in catalina.out.

An error may occur as shown below in some browsers. The solution is to disable TLS 1.3.

sslEnabledProtocols="all,-SSLv2Hello,-TLSv1,-TLSv1.1, -TLSv1.3"

05-Nov-2020 16:46:18.098 SEVERE [https-jsse-nio-192.168.50.25-443-exec-9] org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun
java.lang.NullPointerException
at java.base/sun.security.ssl.HKDF.extract(HKDF.java:93)
 at java.base/sun.security.ssl.HKDF.extract(HKDF.java:119)