Jan 162012
Apache Tomcat

In order to use SSL for server access, we need to create our own public key, which we will use as a certificate. The certificate we are going to create is usually called a self-signed certificate, as it will not be verified with an independent CA, so we cannot authorize as web site owners with it. But, having selfsigned certificate is sufficient enough to have SSL encrypted communication with our server. For development and testing purposes, or for internal applications not accessible outside the company’s network, this is often enough to provide a usable, secure environment.

Creating Keystore with SSL Certificate

All publicly known certificates are stored in a repository called the keystore. The keystore is a file that contains the public and private key data required to encode and decode information using SSL or TLS. Applications that are using SSL must be able to read the keystore file, and use its data as keys to encrypt and decrypt information. The key data in the keystore file can be stored in a number of formats that depend on the tool used to create keystore. Apache Tomcat 7 can read keystores in one of the following formats: PKCS11, PKCS12, and JKS. PKCS11 and PKCS12 formats belong to the standards called Public-Key Cryptography Standards, developed by the RSA Laboratories, which is one of the leading network security companies in the world. JKS format stands for Java KeyStore, which is a Java-specific keystore format. JKS keystore can be created and manipulated using the keytool utility application, distributed as part of Java SDK from version 1.4. Because JKS is simple enough to use and easily accessible as part of Java SDK, we will be using its keytool application to create JKS keystores, which we will use to configure SSL on Tomcat.

Keytool, which we will use to create a self-signed SSL certificate, is located in the JAVA_HOME/bin/ directory. The file name is keytool.exe (on Windows systems), or just keytool, with no extension (on Unix-based systems). Because JAVA_HOME/bin is on the systems path by default after Java installation, you can execute it from any directory on the file system. In order to check if the keytool is available on your system, just type keytool on the command line in the terminal window. You should see the list of all required and optional command line arguments you can use to invoke the application.

The Commands to Generate a New, Self-Signed Certificate in a JKS Keystore

Windows --- keytool -genkeypair -alias tomcat -keyalg RSA -keystore C:\mykeystore
Unix --- keytool -genkey -alias tomcat -keyalg RSA -keystore /home/aleksav/mykeystore

We are using the keytool to generate a new SSL certificate by specifying the -genkeypair argument.The genkeypair argument was named genkey in earlier versions of the Java SDK (earlier than version 1.6), and it is still supported for backward compatibility. Because one keystore can contain multiple public/private key pairs, we will be using the alias “tomcat” to identify our new certificate within the keystore (by specifying the command argument -alias tomcat). We can also specify the algorithm used to generate the key pair, using the –keyalg argument. We will be using the RSA algorithm, a commonly used cryptography algorithm for public and private key generation. Finally, we will specify the file where
our keystore will be saved using the -keystore argument. If you omit this argument, new file named .keystore, will be created in the home directory of the user running the command.

When you press Enter, you will first be prompted for the keystore password. This password will be used to access any certificate stored in the created keystore, so use the usual precaution when deciding on the keystore password. For the purpose of this example, we will set the keystore password to abc123.

After that, you will be prompted to enter some information about the certificate, the owner’s name, the company, and location (country). You are first asked to enter your first and last name. The information you enter is stored in the keystore as the common name (CN) of the certificate. Although it looks confusing, you should enter the host name for the server for which you are generating a certificate.

The reason for this is that, according to HTTPS specification, browsers should match the CN of the provided certificate to the domain name of the requested URL. If they do not match, the user will be presented with a warning in the browser that states that the certificate does not match the domain name of the site they are accessing. Because this decreases the amount of trust users have in the web site, the warning is not something that is desired for the public web site. To avoid this, make sure that any certificate you generate has a valid domain name as the CN, confusingly set as the first and last name value in the keytool interface.

Once you enter all the required details, you will be asked for another password, this time the password for this particular certificate within the keystore. For this example, we will set this password to tomcat123. Both the keystore password we set earlier and the certificate password are used for Tomcat configuration later, so remember them or write them down.
Once completed, you will have the chance to confirm all details entered. Once these are confirmed, you will have your certificate generated and stored in the file you specified as the –keystore argument.

genkey keytool

Configuring Tomcat’s SSL Connector

The first step in configuring SSL with Tomcat is to configure Tomcat’s Connector, which will handle SSL connections over HTTPS. To configure the <Connector> element for SSL, all you have to do is set the SSLEnabled attribute to true, and set the scheme and secure attributes in order that the SSL information is correctly interpreted by the servlets deployed in Tomcat. Along with these basic attributes, you can configure additional details for your SSL configuration relating to the keystore and certificate we generated in the previous section.

cd to TOMCAT_HOME/conf directory and open server.xml file for edit. Search for <Connector and do the below changes to enable SSL.

 scheme="https" secure="true"
 keystoreFile="C:\Java\jdk1.7.0\jre\lib\security\keystore" keystorePass="abc123"
 keyAlias="tomcat" keyPass="tomcat123"

SSL Configuration Tomcat


We first set the SSLEnabled attribute to true, telling Tomcat that this connector handles SSL connections. In addition, we set the scheme attribute to value https, so that all SSL-secure URLs are recognized by the standard https:// protocol identifier; and we need to set secure attribute to true, if we wish to check for an SSL connection within Java servlet code, by calling HttpServletRequest.isSecure() method . Next, we set the port on which the SSL connector will accept incoming connections . Because 443 is the common port number for HTTPS connections, Tomcat itself uses the slight variation 8443 (using the same convention for port 8080 for standard HTTP request, as opposed to the “common” port 80, adding 8000 for the standardized port).

The next bit is the protocol configuration. We used standard HTTP/1.1 protocol, which is implemented in Tomcat’s class org.apache.coyote.http11.Http11Protocol . Http11Protocol is the standard blocking Java HTTP protocol. It is blocking because it uses a single thread to process the incoming requests and dispatch the response back to the browser. You have a choice to use a nonblocking version of Java Tomcat protocol instead, or even an APR Tomcat native protocol. Non-blocking Java protocol must reference its implementing class as the protocol attribute value: org.apache.coyote.http11.Http11NioProtocol. To use Tomcat’s native APR protocol, you must make sure you have Tomcat’s native library on the Tomcat classpath, and reference the APR HTTP connector class name as protocol attribute value: org.apache.coyote.http11.Http11AprProtocol.

The next attribute we configure is the clientAuth attribute . This attribute specifies whether we are using one-way secure certificate authentication or if the client needs to present the valid SSL certificate to the server as well. When using SSL for web applications publicly accessible on the Internet, we don’t require users to authenticate to the server using SSL certificate; to establish a secure connection, it is enough that the client accepts the certificate from the server. However, sometimes the server requires the client to be authenticated as well, usually in a business-to-business scenario, where both client and server are actually computer programs, without any human influence. For this example, we will configure standard public web site SSL connectivity by setting the clientAuth attribute to false.

Finally, we need to set the attributes relating to the keystore and the certificate our Tomcat server will use to encrypt and decrypt SSL traffic. We configure the keystore file path by specifying the keystoreFile attribute, setting it to the absolute path of the keystore file we created in the previous section . At the same time, we specify the password we used for the keystore. And, as the last step, we specify the alias of the actual SSL certificate that can be used to identify it within the specified keystore . We must use the same alias used when creating the certificate, as well as the password for the certificate itself. As you can see, we used the same values as specified when running the keytool application in the previous section.

Now we need to create self signed certificates using openssl(Can be download from http://www.slproweb.com/products/Win32OpenSSL.html)

Check the link for more info on generating certificates.

Now we need to start Tomcat (or restart it if it’s already running). After the startup is completed, you will be able to access Tomcat’s home page by typing https://localhost:8443 URL to your browser’s address bar.


© Incase of any copyright infringements please check copyrights page for faster resolutions.

  3 Responses to “Tomcat SSL configuration steps”

  1. This worked for me, but I want to hide the 8443 port on the address bar, how can i do this?
    I’m using apache2 and tomcat6

Leave a Reply

Show Buttons
Hide Buttons