Tomcat SSL Certificate Installation

CSR and SSL Certificate Installation in Tomcat Web Server

A. Certificate Signing Request (CSR)

  1. Generate Keystore:
    keytool -keysize 2048 -genkey -keyalg RSA -alias mydomain -keystore mydomain.jks
    Enter keystore password: yourpassword
    What is your first and last name? 
    [Unknown]: fully qualified domain name, ex: *,
    What is the name of your organizational unit?
    [Unknown]: division of your organization, ex: IT Department
    What is the name of your organization?
    [Unknown]: legal name of your organization, ex: Google Inc.
    What is the name of your City or Locality?
    [Unknown]: city where your organization is located, ex: Mountain View
    What is the name of your State or Province?
    [Unknown]: state/region where your organization is located (no abbreviations), ex: California
    What is the two-letter country code for this unit?
    [Unknown]: two-letter ISO code for the country, ex: US
    Is CN=*, OU=IT Department, O=Google Inc., L=Mountain View, ST=California, C=US correct?
    [no]: yes
    Enter key password for 
    (RETURN if same as keystore password) just press enter here...
  2. Generate Certificate Signing Request:
    keytool -certreq -alias mydomain -keyalg RSA -file mydomain.csr -keystore mydomain.jks
  3. Send CSR file to your certificate authority (CA)

B. Installing the Certificates to the Keystore

  1. Download your certificate files from your certificate authority and save them to the same directory as the keystore that you created during the CSR creation process. The certificate will only work with the same keystore that you initially created the CSR with. The certificates must be installed to your keystore in the correct order.

  2. Install the Root Certificate file: Every time you install a certificate to the keystore you must enter the keystore password that you chose when you generated it. Enter the following command to install the Root certificate file:

    keytool -import -trustcacerts -alias root -file RootCertFileName.crt -keystore keystore.key

    If you receive a message that says "Certificate already exists in system-wide CA keystore under alias <...> Do you still want to add it to your own keystore? [no]:", select Yes. If successful, you will see "Certificate was added to keystore".

  3. Install the Intermediate Certificate file: If your certificate authority provided an intermediate certificate file, you will need to install it here by typing the following command:

    keytool -import -trustcacerts -alias intermediate -file IntermediateCertFileName.crt -keystore keystore.key

    If successful, you will see "Certificate was added to keystore".

  4. Install the Primary Certificate file: Type the following command to install the Primary certificate file (for your domain name):

    keytool -import -trustcacerts -alias tomcat -file PrimaryCertFileName.crt -keystore keystore.key

    keytool -import -trustcacerts -alias server -file your_site_name.p7b -keystore your_site_name.jks

    If successful, you will see "Certificate reply was installed in keystore". You now have all the certificates installed to the keystore file. You just need to configure your server to use the keystore file.

    Notes: When import p7b, server response error: Input not an X.509 certificate. You need convert PKCS7 to X.509 and import with converted file:

    openssl pkcs7 -print_certs -in your_site_name.p7b -out your_site_name.cer

    keytool -import -trustcacerts -alias server -file your_site_name.cer -keystore your_site_name.jks

C. Import your new Certificate Signed into your keystore

# import Intermediate (Chain) Certificate into your keystore
keytool -import -alias root -keystore mykeystore.jks -trustcacerts -file mycertchain.crt
# import new Certificate into your keystore
# if Certificate imported, error occurred: certificate reply and certificate in keystore are identical
keytool -import -alias tomcat -keystore mykeystore.jks -file mynewcert.crt

(Optional) Import an Existing Certificate Signed into a PKCS12 Keystore

# convert x509 Certificate and PrivateKey to a pkcs12 file
# -chain option to preserve the full certificate chain
# if you don't install the intermediate (chain) certificates with your issued SSL certificate, the trusted-chain certificate might not be established
# visitors attempt to access your site, they might receive a "Security Alert" error
# MAKE SURE put a password on the p12 file, otherwise NULL REFERENCE EXCEPTION
openssl pkcs12 -export -in mycert.crt -inkey myprivatekey.key -out mycert.p12 -name tomcat -CAfile mycertchain.crt -caname root -chain
# convert pkcs12 file to a java keystore
keytool -importkeystore -destkeystore mykeystore.jks -srckeystore mycert.p12 -srcstoretype pkcs12 -alias tomcat
# verify the contents of the keystore
keytool -list -v -keystore mykeystore.jks

D. Configuring your SSL Connector

Tomcat requires an SSL Connector to be configured before it can accept secure connections.

By default Tomcat looks for your Keystore with the file name .keystore in the home directory with the default password "changeit". The home directory is generally /home/user_name/ on Unix and Linux systems, and C:\Documents and Settings\user_name\ on Microsoft Windows systems. You will be able to change the password and file location.

  1. Copy your keystore file (your_domain.key) to the home directory.
  2. Open the file ${CATALINA_HOME}/conf/server.xml in a text editor.
  3. Uncomment the SSL Connector Configuration.
  4. Make sure that the Connector Port is 443.
  5. Make sure the keystorePass matches the password for the keystore and the keystoreFile contains the path and filename of the keystore.

    When you are done your connector should look something like this:

               protocol="HTTP/1.1" port="8443" maxHttpHeaderSize="8192" 
               maxThreads="150" URIEncoding="UTF-8"
               minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true" acceptCount="100"
               scheme="https" secure="true" SSLEnabled="true"
               clientAuth="false" sslProtocol="TLS"
               keyAlias="server" keystoreFile="/home/user_name/your_site_name.jks"
               keystorePass="your_keystore_password" />
               protocol="HTTP/1.1" port="8443" 
               maxThreads="200" URIEncoding="UTF-8"
               scheme="https" secure="true" SSLEnabled="true"
               keystoreFile="${user.home}/.keystore" keystorePass="changeit"
               clientAuth="false" sslProtocol="TLS"

    If you want to using APR connector (use Certificate and Private Key file, without Keystore file)

               protocol="HTTP/1.1" port="8443" 
               maxThreads="200" URIEncoding="UTF-8"
               scheme="https" secure="true" SSLEnabled="true"
               SSLVerifyClient="optional" SSLProtocol="TLSv1+TLSv1.1+TLSv1.2" />
  6. Save the changes to server.xml
  7. Restart Tomcat


Popular posts from this blog