Sunday, February 26, 2017

Tomcat7 - Importing an Existing x509 Certificate and Private Key in Tomcat SSL Configuration

Secure Socket Layer (SSL) is a protocol that provides security for communications between server and client by implementing encrypted data and certificate-based authentication. This step-by-step guide will show you how to configure SSL with Tomcat.

OS: Amazon Linux AMI release 2015.09
Tomcat: 7.0.75

Prerequisite:
1. You already have your site's certificate file, the private key file and the SSL provider's CA file. For example, the "Intermediate CA" file from RapidSSL.
2. Have "keytool" available
3. Note: Tomcat currently operates only on JKS, PKCS11 or PKCS12 format keystores. The JKS format is Java's standard "Java KeyStore" format, and is the format created by the keytool command-line utility. This tool is included in the JDK. The PKCS12 format is an internet standard, and can be manipulated via (among other things) OpenSSL and Microsoft's Key-Manager. That's why we need to convert from x509 to pkcs12

Steps:
1. Convert x509 Cert and Key to a pkcs12 file:
# openssl pkcs12 -export -in mysite.crt -inkey mysite.key -out mysite.p12 -name mysite -CAfile IntermediateCA.crt -caname root

Note: Make sure you put a password on the p12 file - otherwise you'll get a null reference exception when you try to import it.
You should have a "mysite.p12" file after this step. Also, You might want to add the -chainoption to preserve the full certificate chain.

2. Convert the pkcs12 file to a java keystore file:
# /usr/lib/jvm/jdk1.8.0/bin/keytool -importkeystore -deststorepass "password" -destkeypass "password" -destkeystore mysite.keystore -srckeystore mysite.p12 -srcstoretype PKCS12 -srcstorepass "keystore_password" -alias mysite

Now you should have a "mysite.keystore" file.

3. Configuring Tomcat's SSL Connectors. Tomcat's global Connector options are configured in Tomcat's main configuration file, "$CATALINA_BASE/conf/server.xml", so open this file and search for 8443 (Always backup the original file! :)
Until you come across an entry looks like:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
               maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" />

Update it to:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
               maxThreads="150" SSLEnabled="true" keystoreFile="path_to_mysite.keystore"
               keystorePass="keystore_password" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" />

4. Restart Tomcat. Once you're up and running again, test your configuration by connecting to a secure page, using a URL such as https://[yourhost]:8443. If you followed the directions correctly, you should be able to view the page over a secure HTTPS connection!

Now you are all set!

No comments: