Setting up HTTPS with CA certificates on Tomcat

There’s no doubt that every website needs to consider security. And serving critical portions of your site over HTTPS instead of HTTP is an important first step to securing your site.

There are any number of tutorials for setting up SSL on Tomcat. Many of us have generated our own keys and self-signed certificates at some point for side projects and personal development, that part is easy. But when you are ready to take your site public and a browser finds a self-signed certificate and it’s not from a certificate authority (CA), the browser will display all kinds of scary warnings about your site being unknown and potentially dangerous (which objectively it is at that point).

To resolve this, you need to get a certificate from an actual CA. They will verify your identity and send you a certificate that you can use with your site, and your site will become part of the CA’s – and hopefully the web’s – circle of trust.

Some CA’s that provide inexpensive certificates include Thawte, Digicert, and GeoTrust. To get a certificate from a CA, you generate a private key and use it to create a Certificate Signing Request (CSR). Send the CSR to the CA, and they will send you back a certificate that is registered with them that you can use on your site.

Ok here are the steps to setting up HTTPS with CA certificates on Tomcat. If nothing else, take note of step 7 – it’s the hardest step to figure out if you don’t have these directions.

  1. You’ll need the password for your java keystore, or you’ll need to create a new java keystore. If you don’t know it you can always create a new keystore and point tomcat to that. A keystore is just a single file with keys and certificates inside it. Don’t be afraid to experiment, if you create a key in your keystore that you don’t want, you can just delete that key. And since a keystore is just a single file, you can always back it up, restore it, start over, etc. If you forget information about your keystore (such as its password), and tomcat was already configured with it, you can just review the keystore information in tomcat’s server.xml file to recover that information.
    1. list the contents of my keystore: keytool -storepass password -list -keystore keystore.jks
    2. you can always delete a key if you mess something up: keytool -storepass password -delete -alias tomcat -keystore keystore.jks
  2. Read up on the documentation to make sure you understand what goes where. You can start with the Tomcat documentation.
  3. Use openssl to generate a certificate signing request (CSR). This creates a .csr and a .key, the .csr is what you send to your CA and they will return a .crt that corresponds to your private key.
  4. Keep the .key file, and send the .csr to your CA. The CA accepts the CSR and sends back possibly multiple .crt files (a root certificate, possibly some intermediates, and the one for your site).
  5. Create a new keystore if you don’t have one already (see step 1). Creating a new keystore is easy with these handy notes. You can create a keystore with a single dummy key and delete that key later if you want.
  6. You can import all of the certs from the CA into your keystore using the java keytool. The command looks something like this: keytool -storepass password -import -trustcacerts -alias intermediate_cert_name -file intermediate_file.crt -keystore keystore.jks
  7. Here is the tricky part: You also need to import the private key (the .key file created at the same time as the .csr) into the keystore. This is the tricky part because the Java Keytool does not natively import the .key file, and you need to use two steps.
    1. Use openssl to convert the key along with the .crt for your site (the .crt for your site that you got from theCA) into a .p12 file (technically another keystore) that the java keytool can import. The command looks something like this: openssl pkcs12 -export -in www_mycoolsite_com.crt -inkey  mygeneratedkey.key -out www_mycoolsite_com.p12 -name “www_mycoolsite_com_private_key”
    2. Import the .p12 file as a keystore into your keystore. The command looks something like this: keytool  -storepass password -importkeystore -srckeystore www_give3_org.p12 -srcstoretype PKCS12 -destkeystore keystore.jks
  8. Configure tomcat’s server.xml to use the https connector, you will need to modify the port, keystore file location, and keystore password. There are plenty examples of how this is done  online.
  9. Finally, configure the app to serve the site on HTTPS. This is done in web.xml
  10. If the certificate is only good for “www.yourdomain.com” rather than “*.yourdomain.com”, you can test the certificate locally by editing your /etc/hosts file so the site corresponding to the site certificate actually goes to the local machine. Add a line like “127.0.0.1    www.yourdomain.com


And there you have it! Enjoy serving your site with HTTPS, and don’t neglect all the other aspects of security that need to be addresses for your public-facing site.


Advertisements

Leave a comment

Filed under Software Engineering

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s