The Apache Tomcat 5.5 Servlet/JSP Container



Person Information


Apache Tomcat Growth

SSL Configuration HOW-TO

Fast Begin

IMPORTANT NOTE: This Howto refers to utilization of JSSE. When utilizing APR, Tomcat will use OpenSSL, which makes use of a special configuration.

The outline beneath makes use of the variable title $CATALINA_HOME to discuss with the listing into which you may have put in Tomcat 5, and is the bottom listing in opposition to which most relative paths are resolved. Nonetheless, if in case you have configured Tomcat 5 for a number of cases by setting a CATALINA_BASE listing, it is best to use $CATALINA_BASE as an alternative of $CATALINA_HOME for every of those references.

To put in and configure SSL assist on Tomcat 5, you have to observe these easy steps. For extra info, learn the remainder of this HOW-TO.

  1. Create a keystore file to retailer the server’s personal key and self-signed certificates by executing the next command:

    Home windows:


    and specify a password worth of “changeit”.

  2. Uncomment the “SSL HTTP/1.1 Connector” entry in $CATALINA_HOME/conf/server.xml and tweak as vital.
Introduction to SSL

SSL, or Safe Socket Layer, is a know-how which permits internet browsers and internet servers to speak over a secured connection. Which means the info being despatched is encrypted by one aspect, transmitted, then decrypted by the opposite aspect earlier than processing. It is a two-way course of, that means that each the server AND the browser encrypt all visitors earlier than sending out information.

One other essential side of the SSL protocol is Authentication. Which means throughout your preliminary try to speak with an internet server over a safe connection, that server will current your internet browser with a set of credentials, within the type of a “Certificates”, as proof the positioning is who and what it claims to be. In sure instances, the server might also request a Certificates out of your internet browser, asking for proof that you are who you declare to be. This is named “Consumer Authentication,” though in follow that is used extra for business-to-business (B2B) transactions than with particular person customers. Most SSL-enabled internet servers don’t request Consumer Authentication.

SSL and Tomcat

It is very important observe that configuring Tomcat to reap the benefits of safe sockets is often solely vital when operating it as a stand-alone internet server. When operating Tomcat primarily as a Servlet/JSP container behind one other internet server, similar to Apache or Microsoft IIS, it’s often essential to configure the first internet server to deal with the SSL connections from customers. Usually, this server will negotiate all SSL-related performance, then cross on any requests destined for the Tomcat container solely after decrypting these requests. Likewise, Tomcat will return cleartext responses, that shall be encrypted earlier than being returned to the person’s browser. On this setting, Tomcat is aware of that communications between the first internet server and the shopper are going down over a safe connection (as a result of your software wants to have the ability to ask about this), however it doesn’t take part within the encryption or decryption itself.


With a view to implement SSL, an internet server should have an related Certificates for every exterior interface (IP handle) that accepts safe connections. The speculation behind this design is {that a} server ought to present some type of cheap assurance that its proprietor is who you assume it’s, significantly earlier than receiving any delicate info. Whereas a broader clarification of Certificates is past the scope of this doc, consider a Certificates as a “digital driver’s license” for an Web handle. It states what firm the positioning is related to, together with some fundamental contact details about the positioning proprietor or administrator.

This “driver’s license” is cryptographically signed by its proprietor, and is subsequently extraordinarily tough for anybody else to forge. For websites concerned in e-commerce, or every other enterprise transaction during which authentication of id is essential, a Certificates is often bought from a well known Certificates Authority (CA) similar to VeriSign or Thawte. Such certificates may be electronically verified — in impact, the Certificates Authority will vouch for the authenticity of the certificates that it grants, so you may consider that that Certificates is legitimate in the event you belief the Certificates Authority that granted it.

In lots of instances, nonetheless, authentication will not be actually a priority. An administrator might merely need to be certain that the info being transmitted and acquired by the server is personal and can’t be snooped by anybody who could also be eavesdropping on the connection. Happily, Java supplies a comparatively easy command-line instrument, referred to as keytool, which may simply create a “self-signed” Certificates. Self-signed Certificates are merely person generated Certificates which haven’t been formally registered with any well-known CA, and are subsequently probably not assured to be genuine in any respect. Once more, this will likely or might not even be essential, relying in your wants.

Basic Tips about Operating SSL

The primary time a person makes an attempt to entry a secured web page in your web site, she or he is often offered with a dialog containing the small print of the certificates (similar to the corporate and get in touch with title), and requested if she or he needs to simply accept the Certificates as legitimate and proceed with the transaction. Some browsers will present an possibility for completely accepting a given Certificates as legitimate, during which case the person won’t be bothered with a immediate every time they go to your web site. Different browsers don’t present this feature. As soon as accredited by the person, a Certificates shall be thought-about legitimate for a minimum of your entire browser session.

Additionally, whereas the SSL protocol was designed to be as environment friendly as securely attainable, encryption/decryption is a computationally costly course of from a efficiency standpoint. It’s not strictly essential to run a whole internet software over SSL, and certainly a developer can choose and select which pages require a safe connection and which don’t. For a fairly busy web site, it’s customary to solely run sure pages beneath SSL, specifically these pages the place delicate info may presumably be exchanged. This would come with issues like login pages, private info pages, and buying cart checkouts, the place bank card info may presumably be transmitted. Any web page inside an software may be requested over a safe socket by merely prefixing the handle with https: as an alternative of http:. Any pages which completely require a safe connection ought to examine the protocol kind related to the web page request and take the suitable motion if https will not be specified.

Lastly, utilizing name-based digital hosts on a secured connection may be problematic. It is a design limitation of the SSL protocol itself. The SSL handshake, the place the shopper browser accepts the server certificates, should happen earlier than the HTTP request is accessed. Because of this, the request info containing the digital host title can’t be decided previous to authentication, and it’s subsequently not attainable to assign a number of certificates to a single IP handle. If all digital hosts on a single IP handle have to authenticate in opposition to the identical certificates, the addition of a number of digital hosts shouldn’t intrude with regular SSL operations on the server. Bear in mind, nonetheless, that almost all shopper browsers will evaluate the server’s area title in opposition to the area title listed within the certificates, if any (relevant primarily to official, CA-signed certificates). If the domains don’t match, these browsers will show a warning to the shopper person. On the whole, solely address-based digital hosts are generally used with SSL in a manufacturing setting.

Put together the Certificates Keystore

Tomcat at present operates with JKS, PKCS11 or PKCS12 format keystores. The JKS format is Java’s commonplace “Java KeyStore” format, and is the format created by the keytool command-line utility. This instrument is included within the JDK. The PKCS12 format is an web commonplace, and may be manipulated through (amongst different issues) OpenSSL and Microsoft’s Key-Supervisor.

Every entry in a keystore is recognized by an alias string. While many keystore implementations deal with aliases in a case insensitive method, case delicate implementations can be found. The PKCS11 specification, for instance, requires that aliases are case delicate. To keep away from points associated to the case sensitivity of aliases, it’s not really helpful to make use of aliases that differ solely in case.

To import an present certificates right into a JKS keystore, please learn the documentation (in your JDK documentation bundle) about keytool. Be aware that openssl typically provides a readable feedback earlier than the important thing, keytooldoes not assist that, so take away the openssl feedback in the event that they exist earlier than importing the important thing utilizing keytool.

To import an present certificates signed by your individual CA right into a PKCS12 keystore utilizing OpenSSL you’d execute a command like:

For extra superior instances, seek the advice of the OpenSSL documententation.

To create a brand new keystore from scratch, containing a single self-signed Certificates, execute the next from a terminal command line:

Home windows:


(The RSA algorithm must be most well-liked as a safe algorithm, and this additionally ensures common compatibility with different servers and elements.)

This command will create a brand new file, within the house listing of the person beneath which you run it, named “.keystore”. To specify a special location or filename, add the -keystore parameter, adopted by the entire pathname to your keystore file, to the keytool command proven above. Additionally, you will have to replicate this new location within the server.xml configuration file, as described later. For instance:

Home windows:


After executing this command, you’ll first be prompted for the keystore password. The default password utilized by Tomcat is “changeit” (all decrease case), though you may specify a customized password in the event you like. Additionally, you will have to specify the customized password within the server.xml configuration file, as described later.

Subsequent, you’ll be prompted for common details about this Certificates, similar to firm, contact title, and so forth. This info shall be exhibited to customers who try to entry a safe web page in your software, so make it possible for the data supplied right here matches what they are going to anticipate.

Lastly, you’ll be prompted for the key password, which is the password particularly for this Certificates (versus every other Certificates saved in the identical keystore file). You MUST use the identical password right here as was used for the keystore password itself. (At the moment, the keytool immediate will inform you that urgent the ENTER key does this for you mechanically.)

If the whole lot was profitable, you now have a keystore file with a Certificates that can be utilized by your server.

Be aware: your personal key password and keystore password must be the identical. In the event that they differ, you’ll get an error alongside the traces of Can’t get well key, as documented in Bugzilla 38217, which incorporates additional references for this subject.

Edit the Tomcat Configuration File

Tomcat can use two completely different implementations of SSL:

  • the JSSE implementation supplied as a part of the Java runtime (since 1.4)
  • the APR implementation, which makes use of the OpenSSL engine by default.

The precise configuration particulars depend upon which implementation is getting used. The implementation utilized by Tomcat is chosen mechanically until it’s overriden as described beneath. If the set up makes use of APR – i.e. you may have put in the Tomcat native library – then it should use the APR SSL implementation, in any other case it should use the Java JSSE implementation.

To keep away from auto configuration you may outline which implementation to make use of by specifying a classname within the protocol attribute of the Connector.
To outline a Java (JSSE) connector, no matter whether or not the APR library is loaded or not do:

Alternatively, to specify an APR connector (the APR library should be out there) use:

In case you are utilizing APR, you may have the choice of configuring an alternate engine to OpenSSL.

The default worth is So to make use of SSL beneath APR, make sure that the SSLEngine attribute is ready to one thing apart from off. The default worth is on and in the event you specify one other worth, it must be a legitimate engine title.
If you have not compiled in SSL assist into your Tomcat Native library, then you may flip this initialization off SSLRandomSeed permits to specify a supply of entropy. Productive system wants a dependable supply of entropy however entropy may have loads of time to be collected subsequently take a look at programs may use no blocking entropy sources like “/dev/urandom” that can permit faster begins of Tomcat.

The ultimate step is to configure the Connector within the $CATALINA_BASE/conf/server.xml file, the place $CATALINA_BASE represents the bottom listing for the Tomcat 6 occasion. An instance component for an SSL connector is included within the default server.xml file put in with Tomcat. For JSSE, it ought to look one thing like this:

The instance above will throw an error if in case you have the APR and the Tomcat Native libraries in your path, as Tomcat will attempt to use the APR connector. The APR connector makes use of completely different attributes for SSL keys and certificates. An instance of an APR configuration is:

You’ll observe that the instance SSL connector parts are commented out by default. You possibly can both take away the remark tags from across the the instance SSL connector you want to use or add a brand new Connector component of your individual. In both case, you’ll need to configure the SSL Connector in your necessities and setting. The configuration choices and knowledge on which attributes are obligatory for the JSSE primarily based connector (BIO) are documented within the SSL Assist part of the HTTP connector configuration reference. The configuration choices and knowledge on which attributes are obligatory for the APR connector are documented within the HTTPS part of the APR How-To.

The port attribute (default worth is 8443) is the TCP/IP port quantity on which Tomcat will pay attention for safe connections. You possibly can change this to any port quantity you want (similar to to the default port for https communications, which is 443). Nonetheless, particular setup (outdoors the scope of this doc) is important to run Tomcat on port numbers decrease than 1024 on many working programs.

In case you change the port quantity right here, you also needs to change the worth specified for the redirectPort attribute on the non-SSL connector. This permits Tomcat to mechanically redirect customers who try to entry a web page with a safety constraint specifying that SSL is required, as required by the Servlet Specification.

After finishing these configuration modifications, you need to restart Tomcat as you usually do, and you ought to be in enterprise. It’s best to be capable of entry any internet software supported by Tomcat through SSL. For instance, attempt:

and it is best to see the same old Tomcat splash web page (until you may have modified the ROOT internet software). If this doesn’t work, the next part incorporates some troubleshooting suggestions.

Putting in a Certificates from a Certificates Authority

To obstain and set up a Certificates from a Certificates Authority (like, or it is best to have learn the earlier part after which observe these directions:

Create an area Certificates Signing Request (CSR)

With a view to get hold of a Certificates from the Certificates Authority of your alternative you must create a so referred to as Certificates Signing Request (CSR). That CSR shall be used by the Certificates Authority to create a Certificates that can determine your web site as “safe”. To create a CSR observe these steps:

  • Create an area Certificates (as described within the earlier part): Be aware: In some instances you’ll have to enter the area of your web site (i.e. within the discipline “first- and lastname” as a way to create a working Certificates.
  • The CSR is then created with:

Now you may have a file referred to as certreq.csr that you may undergo the Certificates Authority (take a look at the documentation of the Certificates Authority web site on how to do that). In return you get a Certificates.

Importing the Certificates

Now that you’ve your Certificates you may import it into you native keystore. To begin with you must import a so referred to as Chain Certificates or Root Certificates into your keystore. After that you may procede with importing your Certificates.

  • Obtain a Chain Certificates from the Certificates Authority you obtained the Certificates from.
    For industrial certificates go to: up/intermediate.html
    For trial certificates go to: For go to:
    For go to:
  • Import the Chain Certificates into you keystore
  • And eventually import your new Certificates

Here’s a checklist of widespread issues that you could be encounter when establishing SSL communications, and what to do about them.

  • I get “” errors in my log information.

    The JVM can not discover the JSSE JAR information. Comply with the entire instructions to obtain and set up JSSE.

  • When Tomcat begins up, I get an exception like “ {some-directory}/{some-file} not discovered”.

    A probable clarification is that Tomcat can not discover the keystore file the place it’s wanting. By default, Tomcat expects the keystore file to be named .keystore within the person house listing beneath which Tomcat is operating (which can or is probably not the identical as yours :-). If the keystore file is wherever else, you’ll need so as to add a keystoreFile attribute to the component within the Tomcat configuration file.

  • When Tomcat begins up, I get an exception like “ Keystore was tampered with, or password was incorrect”.

    Assuming that somebody has not truly tampered with your keystore file, the almost definitely trigger is that Tomcat is utilizing a special password than the one you used whenever you created the keystore file. To repair this, you may both return and recreate the keystore file, or you may add or replace the keystorePass attribute on the component within the Tomcat configuration file. REMINDER – Passwords are case delicate!

  • When Tomcat begins up, I get an exception like “java.web.SocketException: SSL handshake errorjavax.web.ssl.SSLException: No out there certificates or key corresponds to the SSL cipher suites that are enabled.”

    A probable clarification is that Tomcat can not discover the alias for the server key inside the specified keystore. Examine that the right keystoreFile and keyAlias are specified within the component within the Tomcat configuration file. REMINDER – keyAlias values could also be case delicate!

In case you are nonetheless having issues, an excellent supply of data is the TOMCAT-USER mailing checklist. Yow will discover tips that could archives of earlier messages on this checklist, in addition to subscription and unsubscription info, at

Miscellaneous Suggestions and Bits

To entry the SSL session ID from the request, use:
String sslID = (String)request.getAttribute(“javax.servlet.request.ssl_session”);
For extra dialogue on this space, please see Bugzilla.

For recommendations on utilizing clientAuth on a per-user or per-session foundation, and likewise for utilizing clientAuth with self-signed or expired shopper certificates, please see the dialogue in Bugzilla 34643.


You might also like