Tomcat virtual hosting with SSL

Blog
7/5/18
Lluís Turró Cutiller
8.901
2
ssl tomcat

This 2018 I needed to install an SSL Certificate for a web application. Since Tomcat 9 features virtual hosted web application with differentiated SSL hosts, the next step were easy to guess: move to Java 10 plus Tomcat 9 and make use of these new features. This article goes about the process to its final ending, this web site.

First issues when migrating

Java 9 and above no longer include JAXB. Simply add the JAXB library to Tomcat 9.

Tomcat 9 no longer put the final slash to the URL (does not redirect). Modify conf/context.xml to include mapper attributes:

<Context ... 
	 mapperContextRootRedirectEnabled="true" 
	 mapperDirectoryRedirectEnabled="true"/>

Requirements

  • Tomcat 9, although I've been told 8.5 also supported SSL host virtualization.
  • Java 8 or higher. This example has been tested with Java 10.

Elements used for this article

  • This web site, an open source web application.
  • A Comodo Essential Certificate.
  • A full weekend

Asking for the certificate

If you already have a certificate you may want to skip this part. Otherwise, buy a certificate and continue.

First thing the provider ask for is a Certificate Signing Request. Lets generate one:

openssl req -new -newkey rsa:2048 -nodes -out [yourdomain].csr -keyout [yourdomain].key -subj "/C=[country]/ST=[state]/L=[city]/O=[organization]/OU=[department]/CN=[domain]"

Field

Description

yourdomain

This will be the file name. For example www_domain_whatever, in my case www_turro_org.

country

Two uppercase letters of your country, see ISO 3166-1.

state

Your state or province, as is.

city

Your city.

organization

Your organization name.

department

Department managing de certificate.

domain

As for Comodo Essential, the domain will apply to www.[domain] and [domain] as longer as you use www..

Recomendation: use www.domain, in my case www.turro.org.

Once executed, this command generated two files, yourdomain.csr and yourdomain.key. The CSR file is the Certificate Signing Request, and is the first thing you will need to provide when asking your certificate. The second is the Private Key. Keep them both in a secure place.

Installing the certificate into a keystore

If everything has gone well, you now have a response from the Certification Provider and some certificates in you hard disk. Copy them where you saved previous generated files, CSR and private key. If you followed the instructions, you private key is stored in [yourdomain].key file.

Now, one of the certificates you received is your certificate. The rest are called root certificate and chain certificates.

Change to convenient format

First thing we'll do is convert your private key and your certificate to PKCS12 format. Don't bother now as to why we use this format, I want a single keystore to include the whole bunch of certificates to simplify Tomcat configuration, and it turns out that Tomcat NIO likes this format. So, have it.

openssl pkcs12 -export -in [yourcertificate] -inkey [yourdomain].key -name [yourdomain] -out [yourdomain].p12

Field

Description

yourcertificate

Your certificate is one of those the certification provider sent you. As for Comodo, my certificate was www_turro_org.crt, so it was easy to point out which one was mine.

yourdomain

This will be the file name. For example www_domain_whatever, in my case www_turro_org.

Import private key and certificates into the keystore

This step creates a new keystore file.

keytool -importkeystore -destkeypass [password] -destkeystore [yourdomain].keystore -srckeystore [yourdomain].p12 -srcstoretype PKCS12 -srcstorepass [password]

Now, add the root and chain certificates. Bellow the example with Comodo certificates. You may follow instructions provided for your own certificate provider. Notice that the only pattern used is alias equal to certificate file minus extension.

keytool -import -trustcacerts -alias AddTrustExternalCARoot -file AddTrustExternalCARoot.crt -keystore [yourdomain].keystore
keytool -import -trustcacerts -alias COMODORSAAddTrustCA -file COMODORSAAddTrustCA.crt -keystore [yourdomain].keystore
keytool -import -trustcacerts -alias COMODORSADomainValidationSecureServerCA -file COMODORSADomainValidationSecureServerCA.crt -keystore [yourdomain].keystore

If you followed the instructions, you have a keystore named [yourdomain].keystore with everything required by Tomcat.

Installing the keystore

Let's explain something about Tomcat. Tomcat has a single Connector for SSL configuration. Once you configure your keystore, it will be available by all the web application installed, but will only certificate your domain. So, where SSL hosting virtualization is?

Don't panic, there is SSL hosting virtualization. You achieve the goal by creating SSLHostConfig elements with hostName attribute set to match one of the Host elements its name attribute. One of them will need to be the defaultSSLHostConfigName attribute in the Connector element. Messy? See the server.xml example with the values we used:

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" 
           SSLEnabled="true"
           scheme="https"
           secure="true"
           defaultSSLHostConfigName="[domain]"
           
           ...

           >
    <SSLHostConfig hostName="[domain]">
        <Certificate certificateKeystoreFile="[yourdomain].keystore"
                     certificateKeystorePassword="[password]"/>
    </SSLHostConfig>

    ....

</Connector>

...

<Engine name="Catalina" defaultHost="[domain]">

  <Host name="[domain]"  appBase="/anyfolder" 
        unpackWARs="false" autoDeploy="false">
  </Host>

  ...

</Engine>

Let's suppose we followed the steps with [domain2] values. The server.xml will look like:

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" 
           SSLEnabled="true"
           scheme="https"
           secure="true"
           defaultSSLHostConfigName="[domain]"
           
           ...

           >
    <SSLHostConfig hostName="[domain]">
        <Certificate certificateKeystoreFile="[yourdomain].keystore"
                     certificateKeystorePassword="[password]"/>
    </SSLHostConfig>

    <SSLHostConfig hostName="[domain2]">
        <Certificate certificateKeystoreFile="[yourdomain2].keystore"
                     certificateKeystorePassword="[password2]"/>
    </SSLHostConfig>

    ....

</Connector>

...

<Engine name="Catalina" defaultHost="[domain]">

  <Host name="[domain]"  appBase="/anyfolder" 
        unpackWARs="false" autoDeploy="false">
  </Host>

  <Host name="[domain2]"  appBase="/anyfolder2" 
        unpackWARs="false" autoDeploy="false">
  </Host>

  ...

</Engine>

Now everything is more clear. [domain] is the default SSL configuration, but when somebody visits [domain2] there is a match between SSLHostConfig its hostName attribute and Host its name attribute. Thus, [yourdomain2].keystore will be used.

Restart your Tomcat and... That's all!

Comentaris

Federico vigna 28/8/19
Thank for your guide. I've still have a problem with host's "aliases". I've a Let's Encrypt certificate with multiple hosts (1 for every aliases). In some case if i connect to tomcat with an Alias DNS tomcat use de Default Certificate and so browser often return error like NET::ERR_CERT_COMMON_NAME_INVALID
Lluís Turró Cutiller (Turró.Org) 28/8/19
Have you tried to add a SSLHostConfig for each alias?

Is not my case because I'm forcing the domain using a redirection. Despite which alias the visitor uses, the final domain will always be the Elephant's forced domain.