SSL Certificate Installation in Tomcat Linux Server

For those who uses java server pages via Tomcat server on Linux, providing secure transaction on your website thru SSL protocol is a must.  By this of course  we need to install a CA assigned certificate on the server.

The procedure below is a sample installation of  SSL certificate which tested working on my site .

Prerequisites:

Linux (tested on CentOS 4.3 x64 and later)
OpenSSL
JDK 1.5 ( J2SE 1.5.09 at the time of this writing)
Tomcat server (Apache Tomcat 5.5.20 binary version for linux)

SETUP

1.    Linux
It is assumed that CentOS is ready and updated before installation of other packages.

2.    OpenSSL
You can get openssl by “yum install openssl “

3.    JDK

i.    i.Obtain the lastest version for linux platform at the site below:
http://java.sun.com/javase/downloads/index.jsp

ii.    Choose Linux RPM in self-extracting file for download. The downloaded file has the format like “jdk-1_5_0_09-linux-i586-rpm.bin” .

iii.    Set correct permission on the .bin file by issue chmod 744  <file name>

iv.    Answer the license agreement and a rpm file “jdk-1_5_0_09-linux-i586.rpm” is extracted.

v.    Install the rpm file by the command “rpm –ivh jdk-1_5_0_09-linux-i586.rpm”

vi.    The JDK is then installed under /usr/java/jdk1.5.0_09/

4.    Tomcat Server

i.    obtain Tomcat 5.5.20 binary version at:
http://tomcat.apache.org/download-55.cgi

ii.    Choose core package .zip for download, that is :
http://www.zenteknternational.com/mirrors/apache/tomcat/tomcat-5/v5.5.20/bin/apache-tomcat-5.5.20.zip

iii.    The package is ready for use without compilation. So unzip it at a convenient , eg /usr/

iv.    Now,  tomcat is extracted under “/usr/apache-tomcat-5.5.20” . Tomcat uses the variable $CATALINA_HOME to refer to this directory

v.    These are some of the key tomcat directories, all relative to $CATALINA_HOME:

/bin –     Startup, shutdown, and other scripts. The *.sh files (for Unix systems) are functional duplicates of the *.bat files (for Windows systems). Since the Win32 command-line lacks certain functionality, there are some additional files in here.

/conf – Configuration files and related DTDs. The most important file in here is server.xml. It is the main configuration file for the container.

/logs – Log files are here by default.

/webapps – This is where your webapps go.

vi.    Setting Up Environment and File permission:
cd /usr/apache-tomcat-5.5.20/bin/
chmod  744  *.sh

vii.    Create symbolic link for apache-tomcat
cd /usr/
ln –s apache-tomcat-5.5.20  tomcat

viii.    edit /etc/profile,  add at the end :
export  CATALINA_HOME=/usr/tomcat
export JAVA_HOME=/usr/java/jdk1.5.0_09

ix.    To let Tomcat startup automatically after reboot, we need to add  the following to top of “/usr/apache-tomcat-5.2.20/bin/startup.sh”  :
export JAVA_HOME=/usr/java/jdk1.5.0_09
export CLASSPATH=$CLASSPATH:$JAVA_HOME/lib/tools.jar:$JAVA_HOME/lib/dt.jar:.
export PATH=$PATH:$JAVA_HOME/bin
export CATALINA_HOME=/usr/local/tomcat
/usr/tomcat/bin/catalina.sh start

and add in the “/etc/rc.d/rc.local” :
/usr/tomcat/bin/startup.sh

Installation of SSL cert on Tomcat server

At this stage, it is assumed that the private key and the ssl cert assigned by the CA (eg, Thatwhet  in our case)are ready. Please refer to the appendix for the creation of certification using OpenSSL.

Now we have a cert called, www.freelinuxtutorials.com.crt  assigned by Thawte  (www. Thawte.com) and a private key www.freelinuxtutorials.com.key . We will use to to generate a “keystore” needed by Tomcat. Please follow the steps below:

1.    Create Keystore from CA assigned certificate:
i.    Make directory for the certifications: #mkdir /usr/tomcat/conf/certs

ii.    Change to the cert directory and copy the freelinuxtutorials cert and private key there:

cd /usr/tomcat/conf/certs

iii.    obtain the file thawte-roots .zip   which contains ‘ThawteServerCA.cer’  , the Thawte Root CA at  http://www.thawte.com/roots/

iv.    issue the command  below :
openssl pkcs12 -export -in www.freelinuxtutorials.com.crt -inkey www.freelinuxtutorials.com.key -out www.freelinuxtutorials.com.p12 -name tomcat -CAfile ThawteServerCA.cer -caname root –chain

where

www.freelinuxtutorials.com.crt is the openssl certificate asinged by Thawte
www.freelinuxtutorials.com.key is the private key
ThawteServerCA.cer is the Thawte Root CA
www.freelinuxtutorials.com.p12 is the keystore in pkcs12 format.

1.    Importing the certificate
i.    verify the content the Chain Certificate:

/usr/java/jdk1.5.0_09/bin/keytool -printcert -file ThawteServerCA.cer

ii.    import the Chain Certificate (ie the Thawte Root CA) into the keystore . It is self-signed certificate from the Thawte that contains its well-known public key.

/usr/java/jdk1.5.0_09/bin/keytool -import -alias root -trustcacerts –    file ThawteServerCA.cer

iii.    import the  certificate for  www.freelinuxtutorials.com:

/usr/java/jdk1.5.0_09/bin/keytool -import -alias tomcat -trustcacerts -file www.freelinuxtutorials.com.crt

Configuring Tomcat Server to use SSL communication:

1.    Now set up the HTTPS connector in $CATALINA_HOME/conf/server.xml. Add the following
block after the HTTP connector definition on port 8080:

<!– Define a SSL HTTP/1.1 Connector on port 8443 –>

<Connector port=”443″ maxHttpHeaderSize=”8192″
maxThreads=”150″ minSpareThreads=”25″ maxSpareThreads=”75″
enableLookups=”false” disableUploadTimeout=”true”
acceptCount=”100″ scheme=”https” secure=”true”
clientAuth=”false” sslProtocol=”TLS”
keystoreType=”PKCS12″
keystoreFile=”conf/cert/www.freelinuxtutorials.com.p12″
keystorePass=”XXXXXXX” />

note :

    443 is used as connector port  to  avoid the need to specifiy  port 8443 in the url.   In other words, typing “https://freelinuxtutorials.com/ “  will do the job.  Port 80 is used insteadof 8080 for the same reason :

<!– Define a non-SSL HTTP/1.1 Connector on port 8080 –>
<Connector port=”80″ maxHttpHeaderSize=”8192″
maxThreads=”150″ minSpareThreads=”25″ maxSpareThreads=”75″
enableLookups=”false” redirectPort=”8443″ acceptCount=”100″
connectionTimeout=”20000″ disableUploadTimeout=”true” />

    the keystorePass word is the one asked by  keytool during the keystore generation. It is masked here for security reason. Change it to a correct value in production environment.

2.    Restarting Tomcat Server
a.    ./usr/tomcat/bin/shutdown.sh
b.    /usr/tomcat/bin/startup.sh

Test the SSL connection

Assuming that “ www.freelinuxtutorials.com “  is properly configured in your DNS server,  now request the following URL

https://freelinuxtutorials.com

and you will see a SSL protected test page of the tomcat server. Please note the “lock” symbol which indicates the current page is ssl secured.

———————————————-

The following section is adapted from other documents for creating server certificate for apache.

Getting a Certificate

Before you can use Apache with SSL (via mod_ssl or Apache-SSL), you must create
appropriate server certificate. You can get a server certificate from a commercial
certificate authority or you can create your own certificate authority and then
create certificates for your own servers and clients. The latter method is typically
used for a large organization that wants to manage certificates between campuses
internally.

Getting a server certificate from a commercial CA

To get a signed certificate from a commercial CA, you must meet its requirements.
There are two types of requirements:
You (the requester) must prove that you are the entity you claim to be.
You must submit a Certificate Signing Request (CSR) in electronic form.
The first requirement is usually met by following the CA’s guidelines for verifying
individuals or organizations, so you must consult with your chosen CA to learn how
to proceed. Typically, if you are planning on getting your Web server certified, be
prepared to submit copies of legal documents, such as business registration or
incorporation papers. Alternatively, you can create a CSR using OpenSSL.
The very first step in creating a CSR is to create a private key for your server.
Then you need to create a certificate signing request that needs to be sent to a
commercial certificate authority. After you have been approved by a commercial
certificate authority you can install the certificate on your server and use SSL with
Apache. I discuss these steps in detail in the following sections.

Generating a private key
To generate an encrypted private key for a Web server host called www.domain.
com run:

openssl genrsa -des3 -out www.domain.com.key 1024 -rand
/dev/urandom

When you run this command, you are asked to enter a pass phrase (that is,
a password) to encrypt the private key with it. Because the private key is encrypted
using the des3 cipher, you are asked to enter the pass phrase every time your
server is started. If this is undesirable, you can create a nonencrypted version of the private key by removing the –des3 option in the above command line. I highly
recommend that you use an encrypted private key to ensure a high-level of security.

After all, you do not want someone else with access to your server to be able to see your private key. Listing 19-1 shows the content of the www.domain.com.key file.
Listing 19-1: The Content of www.domain.com.key File
—–BEGIN RSA PRIVATE KEY—–
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,C48E9F2F597AF968
47f4qGkVrfFfTNEygEs/uyaPOeAqksOnALtKUvADHKL7BhaB+8BrT/Haa7MHwEzU
jjaRd1XF1k1Ej3qH6d/Zl0AwVfYiAYvO1H3wQB2pllSuxui2sm7ZRkYUOpRMjxZI
/srHn/DU+dUq11pH3vJRw2hHNVjHUB0cuCszZ8GOhICa5MFGsZxDR+cKP0T2Uvf5
jlGyiMroBzN0QF0v8sqwZoSOsuKHU9ZKdA/Pcbu+fwyDWFzNfr8HPNTImlaMjGEt
i9LWZikzBW2mmaw79Pq6xSyqL+7dKXmiQL6d/bYiH0ZUYHjMkJtqUp1fNXxJd4T6
kB8xVbvjPivo1AyvYK0qmmVQp7WDnEyrrYUZVyRu0a+1O50aTG2GnfSy32YGuNTY
lMB3PH5BuocSRp+9SsKKTVoW0a01n0RtgVk/EZTO2Eo94qPcsZes6YyAwY4fFVAw
gG/G3ZJCPdjBI2YLmvhua3bvp9duc5CXmKDxOO49VvjbEB/yvi9pLbuj8KuAt4ht
fZcZB94wxrR/EMGODs2xgNhH+SwEf5Pc/bPUMRCq/0t6F/HJ47jVnUf17tdtoTT7
UbQQVyAsr9tKSFzsRKMOGBO4VoenkD5CzUUF3iO/NaXSs/EFu9HG1ctWRKZEVIp/
MSJBe3jYDXbmeGdQGNJUExpY64hv1XoNd0pAJk0E622o2al1raFusl2PotNvWYdI
TShgoIHSmNgQQLCfssJH5TABKyLejsgQy5Rz/Vp3kDzkWhwEC0hI42p0S8sr4GhM
6YEdASb51uP3ftn2ivKshueZHpFOvS1pCGjnEYAEdY4QLJkreznM8w==
—–END RSA PRIVATE KEY—–

Generating a certificate signing request
Now you need to generate the CSR using your private key as follows:
openssl req -new -key www.domain.com.key -out www.domain.com.csr
If you encrypted the private key earlier, you are asked to enter the pass phrase for
the private key. Enter the appropriate pass phrase. Then, you are asked to enter
country name, state, city, organization name, organization unit/department name,
common name (that is, your name if the certificate request is for yourself, or your
server’s hostname), e-mail address and some optional information such as a
challenge password and an optional company name.
At this point, you need to submit your CSR to a CA such as Thawte. Because the
certification process involves verification of your individual or business identity
documents, it might take a few days to a few weeks or even months before you
receive your certificate. The following section uses Thawte as the chosen CA.

If you are in a rush to get the certificate to get started with testing or have some
other reason why you need a temporary certificate fast, ask your CA. It might have
a way to provide you with a temporary, untrusted certificate. For example, Thawte
will let you submit your CSR via the Web for a temporary certificate, which you will
receive in minutes via e-mail.
After you get the server certificate from a commercial CA, you can install the
certificate file per their instructions. This step is usually quite simple. You are likely
to be asked to copy the file into a directory and restart the server.
If you are not interested in getting a signed certificate from a commercial CA, you
can create your own CA and certify entities such as servers or users at any time.
I show you how in the following section.

Creating a private certificate authority
As stated earlier, private self-signed certificates are not suitable for Internet use in the sense that users at large should not trust such certificates. However, if you want to be able to issue internal, company-wide certificates to your departments and do not want the hassle of going through the third-party commercial CA verification,you must use a private CA.

It might be possible to get a cross-linked certificate for your private CA from a
commercial CA. In such a case, your private CA will be chained to the commercial
CA and thus everyone should trust any certificate that you issue. However,
the commercial CA might limit your certificate-granting authority to your own
organization to ensure that you do not compete with the CA.

Follow these steps to create a private self-certified CA using OpenSSL:

1. Download the latest version of the ssl.ca-version.tar.gz script
distribution from the user-contributed software section (www.openssl.org/
contrib) of the OpenSSL Web site. Extract this file to a directory of your
choice. A subdirectory called ssl.ca-version will be created. You will find
a set of sh scripts in the directory.

2. Run the new-root-ca.sh script to create a self-signed root certificate for
your private CA. You will be asked to enter a pass phrase. This pass phrase is
required for signing future certificates.

3. To create a server certificate, run the new-server-cert.sh www.domain.com
script to create a server’s private and public key. You will be asked to enter
distinguished name fields for the new server certificate. The script will also
generate a CSR, which you can send to a commercial CA later if you so choose.

4. Run the sign-server-cert.sh script to approve and sign the server
certificate you created using the new-server-cert.sh script.

5. Run the new-user-cert.sh script to create a user certificate. When signed
by a commercial certificate authority, user certificates can be used with a Web browser to authenticate users to remote services. However, user certificates are not commonplace because of a lack of understanding about them and a lack of available client and server software.

6. Run the sign-user-cert.sh script to sign a user certificate. Also, run the
p12.sh script to package the private key, the signed key, and the CA’s public
key into a file with .p12 extension. This file can then be imported into
applications such as e-mail clients for use.
Now you are ready to make use of OpenSSL with various applications. OpenSSL is
an integral part of security. The more you use OpenSSL, the more you will find it easy to incorporate in many services.