How to use SSL certificates with Java, Tomcat and cPanel?

Published on Nov 21 2011 in Control Panels Java Tomcat

In Java hosting there are 2 basic ways you can secure data flow to/from your application server: SSL certificate in application server or SSL certificate in web frontend (e.g. Apache).

Get dedicated IP and setup SSL certificate for your domain in cPanel.

Note that on newer cPanels where SNI is supported you do not need dedicated IP anymore to install your SSL certificate. This will secure any requests to your domain on HTTPS port, no matter if they are to be served by Apache or by Tomcat thanks to internal mapping of selected or all requests between Apache web server and your application server e.g. Apache Tomcat. The mapping is made internally (within the same machine over loopback interface) via either mod_jk or mod_proxy_ajp. You can choose mapping method and include or exclude URLs using JVMHost.com custom Java Control Panel (JCP).

Install SSL certificate directly in application server using shared or dedicated IP.

We will use JDK 1.6.0 and Tomcat 7 as example in this article and describe method 2 as method 1 is easy and self-explaining. Let's go!

Prepare keystore and domain key (private key)

Keystore is a file where key/certificate information is stored. We will create it in home directory which is its default location under Linux. Default name for keystore file is .keystore unless specified in the command line.

[~]# cd ~
[~]# keytool -genkey -keyalg RSA -alias tomcat.jvmhost.net -validity 1000 -keysize 2048

You will be prompted for passwords to secure keystore and individual keys. When asked What is your first and last name? enter the domain name you want to get certificate for (it will become Common Name certificate attribute).

Enter keystore password:  
Re-enter new password: 
What is your first and last name?
[Unknown]:  tomcat.jvmhost.net
What is the name of your organizational unit?
[Unknown]:  Demo Unit
What is the name of your organization?
[Unknown]:  Demo Tomcat
What is the name of your City or Locality?
[Unknown]:  Chicago
What is the name of your State or Province?
[Unknown]:  Illinois
What is the two-letter country code for this unit?
[Unknown]:  US
Is CN=tomcat.jvmhost.net, OU=Demo Unit, O=Demo Tomcat, L=Chicago, ST=Illinois, C=US correct?
[no]:  yes

Enter key password for 
(RETURN if same as keystore password):

NOTE: Please specify the same password for the keystore and the key entry or else you may receive the following error message when you restart the Tomcat: java.security.UnrecoverableKeyException: Cannot recover key. The .keystore has been created in current (home) directory. You can list its contents or just a single entry.

[~]# keytool -list -keystore .keystore
Enter keystore password:  
 
Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

tomcat.jvmhost.net, Aug 3, 2011, PrivateKeyEntry, 
Certificate fingerprint (MD5): 9C:F3:D6:E0:07:95:DB:83:9A:09:02:D3:17:3D:73:66

[~]# keytool -list -alias tomcat.jvmhost.net 
Enter keystore password:  
tomcat.jvmhost.net, Aug 3, 2011, PrivateKeyEntry, 
Certificate fingerprint (MD5): 9C:F3:D6:E0:07:95:DB:83:9A:09:02:D3:17:3D:73:66

Uncomment SSL connector in Tomcat's conf/server.xml and add keystore attributes

keystoreFile="/path/to/your/.keystore"
keystorePass="Your password"
keyAlias="tomcat.jvmhost.net"

After the changes SSL connector may look like:

<Connector port="10105" protocol="HTTP/1.1" SSLEnabled="true"       
  maxThreads="150" scheme="https" secure="true"                 
  clientAuth="false" sslProtocol="TLS" 
  keystoreFile="/path/to/your/.keystore" keystorePass="Your password" 
  keyAlias="tomcat.jvmhost.net" />

You may now access Tomcat on your SSL port e.g. https://tomcat.jvmhost.net:10105/ and you should get untrusted certificate prompt. When you open certificate details you will see data entered at keystore creation time. This is self-signed certificate. You may want to have a qualified (CA signed) certificate dedicated to your domain though. Read on.

If you want your browser to authenticate to the Tomcat you may want to read about clientAuth attribute in Tomcat 7 SSL client authentication chapter.

While using the self signed certificate that you created above your browser may be opening security warning popups. You may accept the certificate confirming its validity and the warning should not be coming back as an exception will be added and saved in browser's repository.

If you want to generate and set up a qualified (or self-signed) certificate exactly for your domain then continue reading.

Note: cPanel is currently (Q4 2016) offering free and auto-renewable certificates valid for 3 months thru AutoSSL feature. These are issued by cPanel, Inc. on behalf of Comodo or by Let's Encrypt. You can also convert them and load into .keystore if needed.

Generate CSR (Certificate Signing Request) for your domain

[~]# keytool -certreq -keyalg RSA -alias tomcat.jvmhost.net -file certreq.csr

Submit certreq.csr to your certificate issuer (you can order SSL certificate at JVM Host). Set Tomcat as server type when submitting CSR if possible. This will generate certificate in correct format. Otherwise you may need to convert formats before using the certificate with keytool. Example certreq.csr content is below.

-----BEGIN NEW CERTIFICATE REQUEST-----
MIICvjCCAaYCAQAweTELMAkGA1UEBhMCVVMxETAPBgNVBAgTCElsbGlub2lzMRAwDgYDVQQHEwdD
...
+7g4w8G3qs/BQuUTvPq82WTWQhW5EA==
-----END NEW CERTIFICATE REQUEST-----

When you receive the certificate from the issuer import any intermediate CA certificates provided with your certificate.

[~]# keytool -import -trustcacerts -alias PositiveSSLCA -file PositiveSSLCA.crt
Enter keystore password:  
Certificate was added to keystore

Then import your domain certificate.

[~]# keytool -import -trustcacerts -alias tomcat.jvmhost.net -file tomcat_jvmhost_net.crt
Enter keystore password:  
Certificate reply was installed in keystore

Now restart Tomcat so that it rereads the keystore with the new certificate and you should see your qualified certificate in action when accessing the Tomcat on its HTTPS port https://tomcat.jvmhost.net:10105/. Of course, if you have a dedicated IP, you can use port 443 in connector configuration and call just https://tomcat.jvmhost.net/ without any explicit port. Congratulations, your are done!

Articles