1) System Requirements :---
| OS Version Used | Tomcat Version Used | JDK Version |
| SunOS sol 10 | Tomcat-5.5.23 | JDK-1.5.x |
2) Prerequisites:-
- Use the same version of JDK which your tomcat is using.
- Include the Path of the JDK in your current working directory.
- To check path type the following in the Solaris box----
- echo $PATH
- To set the Path in the current directory use the following----
- PATH=$PATH:<path 1>:<path 2>:……….<path n>
3) SSL communication with Tomcat
This document describes briefly how to enable Tomcat’s SSL capabilities and shows how to make use of it.
We will discuss here an Utility that Java provides.
Java Keytool
Java provides a command line tool to create an SSL certificate, which is requested by Tomcat when it tries to initialize. If we already got an officially signed certificate, we don’t need this step. keytool is a key and certificate management utility. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers.
A certificate is a digitally signed statement from one entity (person, company, etc.), saying that the public key (and some other information) of some other entity has a particular value. When data is digitally signed, the signature can be verified to check the data integrity and authenticity. Integrity means that the data has not been modified or tampered with, and authenticity means the data indeed comes from whoever claims to have created and signed it.We will discuss here to generate a self signed certificate as well as certificate through posting a CSR and then importing certificate to the keystore.
SSL Configuration By Generating a self signed certificate
I have installed tomcat-5.5.23 in my home directory. At first I will create a self signed certificate by using
Keytool utility from JDK. Where the JDK is installed in /usr/jdk1.5.0_13/bin/ directory.
I have configured tomcat to listen on 8590 for http and 8570 for https.
For this use –
/usr/jdk1.5.0_13/bin/keytool -genkey -alias tomcat -keyalg RSA -validity 365 -keystore keystore.key
It will prompt for the following details ----
What is your first and last name?
[Unknown]: MY NAME
What is the name of your organizational unit?
[Unknown]: SERVER SOFTWARE
What is the name of your organization?
[Unknown]: COMPANY
What is the name of your City or Locality?
[Unknown]: KOLKATA
What is the name of your State or Province?
[Unknown]: WB
What is the two-letter country code for this unit?
[Unknown]: IN
Is CN=MY NAME, OU=SERVER SOFTWARE, O=COMPANY, L=KOLKATA, ST=WB, C=IN correct?
[no]: yes
What is the name of your organizational unit?
[Unknown]: SERVER SOFTWARE
What is the name of your organization?
[Unknown]: COMPANY
What is the name of your City or Locality?
[Unknown]: KOLKATA
What is the name of your State or Province?
[Unknown]: WB
What is the two-letter country code for this unit?
[Unknown]: IN
Is CN=MY NAME, OU=SERVER SOFTWARE, O=COMPANY, L=KOLKATA, ST=WB, C=IN correct?
[no]: yes
This will generate a new Keystore name as Kestore.key in the home directory.This new keystore contains self signed certificate which is valid for 365 days.
Now we will configure our tomcat to use SSL utility.For this we will move above generated keystore to our tomcat conf directory.
We will now add SSL connector in the main configuration file in tomcat.For this purpose add the
following lines in server.xml on tomcat –
<Connector port="8570" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25"
maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true" clientAuth="false"
sslProtocol="TLSkeystoreFile="/export/home/me/tomcat-test/conf/keystore.key"
keypass="******" />
Since the password is different from “changeit” which is the default one, I have added the password attribute as well:
KeystorePass=”********”.Now we need to restart the tomcat server for the changes to take effect.
Now access the URL for both http/https protocol to ensure that tomcat is working with SSL support.
https:// hostname:8570/
http:// hostname:8590/
I have to use a different machine name or URL if I have configured tomcat in any other Unix Machine .
Finally we will get the Home Page for the tomcat configured.
SSL Configuration By Importing Trusted Certificate Authority
This can be summarized below—
Create a keystore for Tomcat: using Java key tool.
Generate a Certificate Sigining Request (CSR).
Install the Intermediate Certificate file.
Install the Root Certificate file.
Configure Tomcat: uncomment the HTTPS section, restart, make a smoke test with Internet Explorer.
Create a HTTPS URL connection and load your data.
With the following command we create a new keystore:
%JAVA_HOME%/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore <keystore_filename>
With this we can create CSR:
%JAVA_HOME%/bin/keytool -certreq -keyalg RSA -alias tomcat -file my.csr -keystore <keystore_filename>
With the following command we can Import the Chain Certificate into our keystore
%JAVA_HOME%/bin/keytool -import -alias tomcat -keystore <keystore_filename> -trustcacerts -file <filename of the chain certificate>
We can import our new Certificate by the following command
%JAVA_HOME%/bin/keytool -import -alias tomcat -keystore <keystore_filename> -trustcacerts -file <certificate filename>
Finally we can modify our server.xml file and restart tomcat to use SSL as explained above.
4) Common Problems and their Solutions
1 ) Dealing With Client Side Authentication Issues
Trying to connect to Tomcat via Java and HTTPS may result in the following exception:
“javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException:”
No trusted certificate found.
When Tomcat does not respond with a signed certificate the client side SSL layer does not accept it. This
means, the JRE could not authenticate the server’s certificate by means of its local keystore and therefore the
server might not be the one it claims to be. Each JRE contains a pre configured standard keystore (or
truststore) for authenticating signed certificates.Have a look at:
%JAVA_HOME%/jre/lib/security/cacerts
Solution :
Providing a Custom Key Store
Recommended procedure to avoid the SSL handshake exception is done by letting the
JRE address a keystore containing server’s real certificate. For testing purpose we could simply use the one
we have created during Tomcat configuration. Just pass the keystore location and password as JVM
parameters when you start your application.
One step ahead it’s maybe required to move an unsigned Tomcat certificate from Tomcat’s keystore into your
own, or even the JRE keystore. Thereby all required certificates could accumulate in one repository.
a) Export:
%JAVA_HOME%/bin/keytool -export -alias tomcat -keypass changeit -file mycert
b) Import:
%JAVA_HOME%/bin/keytool -import -file mycert -keypass changeit -keystore JAVA_HOME%/jre/lib/security/cacerts
2) Error: “java.io.exception: sequence tag error"
Solution :
The certificate is missing the header and footer lines. When copying the certificate from the email received, be sure to include the "-----Begin Certificate-----" and "-----End Certificate-----" lines. These lines determine the beginning and ending points of the certificate. You will also want to make sure you delete any white or blank spaces before and after these lines.
3) Error:''Exception: Failed to establish chain from reply'' Due to Certificate in incorrect format"
Solution :
This error is related to the format the certificate has been downloaded in. Please make sure you download the (default) PKCS#7 format certificate and import this into your keystore. JDK prefers this format, which contains a complete certificate chain and which includes your certificate, as well as the signer certificates (i.e Root CA
4)Error: "java.io.IOException: keystore was tampered with, or password was incorrect
Solution :
1.The error occurs because the incorrect keystore file is being specified.
Check if the correct keystore alias was used and if the keystore exists.
If the key store is corrupted, then a new keystore would need to be created, a new private key generated and the certificate reissued.
If the password was incorrect and cannot be remembered, then the certificate must be reissued.
5)Error: "java.security.cert.CertificateParsingException: signed overrun, bytes = 84"
Solution :
The error occurs because the -alias parameter was omitted from the import command.
Please import the Certificate into your key store using the following command: key tool -import -alias [keyentry_friendly_name] -trustcacerts -file mycert.crt -keystore [keystore_name].
Please specify the correct key store name and keyEntry alias(friendly name).
6)Error: "Connection refused" when connecting with Netscape browser
Solution :
The error occurs because the incorrect keystore password is being referenced by the 'KeystorePass' directive in the server.xml configuration file.
1.Please open up the server.xml config file using a text editor (JAKARTA_HOME/conf/server.xml)
2. Please search for the secure <connector> element in your config file, by default it should look something like this:
<!-- Define an SSL HTTP/1.1 Connector on port 8443 -->
<Connector
className="org.apache.catalina.connector.http.HttpConnector"
port="8443" minProcessors="5" maxProcessors="75"
enableLookups="true"
acceptCount="10" debug="0" scheme="https" secure="true">
clientAuth="false"
keystoreFile="ssl/.keystore"
keystorePass="password"
protocol="TLS"/>
</Connector>
Please make sure the 'KeystorePass' directive is referencing the correct keystore password.
3. Please restart the jakarta
7)Error: “initKeyStore: java.io.FileNotFoundException"
Solution :
The reason why this error occurs is because Tomcat cannot find the keystore file where it is looking. By default, Tomcat expects the keystore file to be named .keystore in the user home directory under which Tomcat is running.
If the keystore file is in a differeny directory to the user profile directory under which Tomcat is running you will need to add a keystoreFile attribute to the FACTORY element in the Tomcat configuration file. Once the attribute under FACTORY has been added please restart the jakarta
8)Error: "java.security.UnrecoverableKeyException: Cannot recover key"
Solution :
This error occurs because the keystore password and the keyEntry password are different.
Generate a new keystore, keyEntry and CSR and specify the same password for the keystore and the keyEntry.
5) References
a) https://www.thawte.com
b) http://tomcat.apache.org
c) http://www.verisign.com