Recently a client of mine required SSL to be enabled for Apache Tomcat. A 3rd party had installed their software and setup Tomcat, but required it to be configured for SSL This was a rather large pain to get going, but now that it’s working, I feel it would be rather helpful having the full instructions on what to do to get it all up and running.
Basically how it works is that you have to create a KeyStore that will reside on the server that’s running Tomcat. This KeyStore will contain certificates for the server and will be referenced by a server.xml file which controls Tomcat.
Generate the CSR
1. Create a new folder in C: called “Tomcat SSL”. This will house all the certificates and KeyStores associated with this task.
2. From a Command Prompt, navigate to the Java folder and find keytool.exe
Usually located here: C:\Program Files (x86)\Java\jre1.8.0_91\bin
3. Create the new KeyStore by typing in the following command:
keytool.exe -genkey -alias [fqdn of website] -keyalg RSA -keystore “C:\Tomcat SSL\Keystore.jks”
This will then ask you to type in a password. It doesn’t have to be too complex, but make sure it’s something you can remember.
CMD will then prompt you for the following information:
- First and Last name
- Name of organisation unit
- Name of organisation
- City of Locality
- State or Province
- two-letter country code for this unit
Once you’ve done that, confirm that you have all the details correct by typing in yes and then hitting enter.
4. Generate a CSR to create the certificate from. To do this, type the following command:
keytool.exe -certreq -keyalg RSA -Alias [fqdn of website] -KeyStore [Location of Keystore.jks file] -File “C:\Tomcat SSL\tomcatssl.csr”
This will then ask you to type in the password that you had set in the last section to confirm that you have permissions to do this. Once you have done this, you will need to go to a CA and generate a new key. I personally use
DigiCert to get this done. When you create the certificate, it will ask you what platform you want to generate it for. Choose
tomcat.
Once DigiCert have generated the certificate and you go to download it, it will ask you how you wish to download this. Select that you want to have all the individual .crt files within a .zip file.
This will include the certificate that you have just generated, as well as the root certificate and also an intermediary certificate. You can work out which certificate is which by viewing the certificate, then clicking on Certification Path
The order will usually be the following
- TrustedRoot.crt – Root
- DigiCertCA.crt – Intermediary
- [fqdn of website].crt
Knowing which cert is which will come in hand in the next step.
Import the Certificates
5. Import the RootCA certificate with the following command:
keytool.exe -import -alias root -keystore “C:\Tomcat SSL\keystore.jks” -trustcacerts -file “C:\Tomcat SSL\TrustedRoot.crt”
6. Enter the KeyStore password to allow this certificate to be imported.
7. Import the Intermediary certificate with the following command:
keytool.exe -import -alias intermed -keystore “C:\Tomcat SSL\keystore.jks” -File “C:\Tomcat SSL\DigiCertCA.crt”
8. Enter the KeyStore password to allow this certificate to be imported
9. Import the final certificate with the following command:
keytool.exe -import -alias [fqdn of website] -keystore “C:\Tomcat SSL\keystore.jks” -File “C:\Tomcat SSL\[fqdn of website].crt”
10. Enter the KeyStore password to allow this certificate to be imported.
This now finishes the requirements to get the certificates installed and ready to go on the Tomcat server. Now we have to tell Tomcat to use SSL and to use the specific KeyStore to obtain the certificates etc.
Configure Tomcat’s SSL Connectors
1. Go to the following location
C:\Program Files (x86)\Apache Software Foundation\Tomcat 8.0\conf
2. Find server.xml and open this up in Notepad
3. Scroll down the document until you can find the following section:
<!– Define a SSL/TLS HTTP/1.1 Connector on port 8443
This connector uses the NIO implementation that requires the JSSE
style configuration. When using the APR/native implementation, the
OpenSSL style configuration is required as described in the APR/native
documentation –>
4. Right under this section, you will see the Connector Port showing as 8443 and then what protocol it is
5. Remove what has been written there and type in the following:
<Connector port=”443″ protocol=”HTTP/1.1″
maxThreads=”150″ SSLEnabled=”true” scheme=”https” secure=”true”
clientAuth=”false” SSLProtocol=”TLS”
keystoreFile=”C:\Tomcat SSL\keystore.jks”
keystorePass=”[password of keystore]” />
6. Changing the port from 8443 to 443 will mean that you don’t have to go to https://localhost:8443, but you can just go to https://localhost.
7. That whole section should look like the following:
<!– Define a SSL/TLS HTTP/1.1 Connector on port 8443
This connector uses the NIO implementation that requires the JSSE
style configuration. When using the APR/native implementation, the
OpenSSL style configuration is required as described in the APR/native
documentation –>
<Connector port=”443″ protocol=”HTTP/1.1″
maxThreads=”150″ SSLEnabled=”true” scheme=”https” secure=”true”
clientAuth=”false” SSLProtocol=”TLS”
keystoreFile=”conf/keystore.jks”
keystorePass=”[password of keystore]” />
8. Find the Apache Tomcat service and restart it
9. Once you have restarted the serivce, you should be able to go to https://localhost and it will load the tomcat webpage using TCP443.
10. Remember that because you’re accessing it internally and testing using localhost, it’s going to give you a certificate error. This will not happen if you’re accessing it using the FQDN of the website
