This guide explains how to run eMuesum over HTTPS. For in-depth details and Tomcat settings, see the Tomcat 9.0 How-To.
The process consists of these steps:
Choose the protocol to be used by Tomcat
Create a keypair which consists of a private key and a certificate, and create a Certificate Signing Request (CSR) that includes the certificate
Send the CSR to a Certificate Authority (CA) to obtain a signed certificate
Create a keystore that includes both the private key and the signed certificate
Configure Tomcat to enable HTTPS and use the Keystore
Tomcat supports two protocols for handling HTTPS, the APR/native and the NIO, which are described below. Each protocol uses a different keystore format. Though it is possible to convert from one format to the other, we recommend creating the keystore, certificate, and key files in the format specific to the protocol from the beginning.
The APR/native protocol requires the installation of OpenSSL and the Tomcat Native library. If you choose this option, use OpenSSL to create the certificate in the PKCS #12 format.
The NIO protocol is implemented in pure Java and uses the JKS keystore type. If you choose this option, you can use the Keystore Explorer to create the certificate and the keystore.
The first step is to create a keypair that consists of a private key and certificate, which will be wrapped in a Certificate Signing Request (CSR).
Install OpenSSL (or download the OpenSSL binaries)
For Windows, unpack the downloaded file to C:\eMuseum\ and define environment variables by opening a command prompt and running these two commands:
Create a private key by running the following command in a command prompt:
(replace collections-mymuseum-org with the domain of your eMuseum instance)
Create a Certificate Signing Request (which includes the certificate) by running the following command in a command prompt:
(replace collections-mymuseum-org with the same value as in the previous step)
When prompted, provide the following information:
Enter Country Name (e. g. US)
Enter State or Province Name (e. g., New York)
Enter Locality Name (e. g., New York)
Enter the Organization Name (e. g., Gallery Systems)
Enter Organizational Unit Name (e. g. Gallery Systems)
Enter Common Name (e. g. collections.mymuseum.org) The Common Name (CN) must be the fully qualified domain name of the site—e. g. collection.mymuseum.org
Enter "Email Address" (e. g. siteadmin@mymuseum.org)
Press enter when prompted for "challenge password". Not required.
Press enter when prompted for "company name". Not required.
Download and install the KeyStore Explorer application
Create a keypair that:
Go to the Tools menu and select Generate Key Pair
In the Generate Key Pair prompt, select RSA and make sure the Key Size is set to 2,048
Click OK
On the Generate Key Pair Certificate screen:
Choose Version 3 as the version
Select SHA-256 with RSA as the signature algorithm
Select 1 to 5 years for the validity period The validity period determines how long the certificate will be valid for
Click the @ icon
Enter the requested information The Common Name (CN) must be the fully qualified domain name of the site—e. g. collection.mymuseum.org
Click OK
Click OK
Enter a password for the key store
Click OK
Click OK
Click the save icon or go to the File menu and select Save
Browse to the root of the Tomcat installation directory
Enter a file name value such as collection.mymuseum.org.jks Change this value to match your eMuseum domain plus .jks
Click Save
Create a Certificate Signing Request (CSR):
Right-click on the private key and select Generate CSR
Choose PKCS #10
Select SHA-256 with RSA
Browse to select a location to save the .csr file to
Enter a file name value such as collection.mymuseum.org.csr
Click OK
Use the CSR file generated in the steps above to obtain a signed certificate from your preferred Certificate Authority (CA). You will get back a signed certificate and, optionally, an intermediate and a root certificate that are specific to the CA.
The PKCS #12 format is appropriate for using the APR/native protocol. If the private key and the certificate have been created using OpenSSL, they are already in the PKCS #12 format. Make sure that the intermediate certificate is included in the .crt file together with the signed certificate.
The JKS format is the right format for using the NIO protocol. If the private key and the certificate have been created with the Keystore Explorer, import the signed certificate back into the keystore:
Right-click on the private key and select Import CA Reply → From File
Browse to the signed certificate from the CA
Select the certificate and click OK
Go to the Tools menu and select Import Trusted Certificate
Browse to the intermediate certificate file and select it If the intermediate file contains more than one certificate, back up the file and delete all but the first.
Click OK to import the certificate
Click the save icon to save the changes to the key store. If prompted, re-enter the key store password.
Depending on the protocol, the configuration is slightly different. In both cases, copy the (Keystore) file(s) to the <TOMCAT_HOME>/conf/ folder.
Open <TOMCAT_HOME>/conf/server.xml in a text editor with administrator permissions
For Tomcat 8.5 and above add the following block under the <Service> element:
CopyXML
For Tomcat 8 and below add the following block under the <Server> element:i
CopyXML
Save the changes to server.xml
Restart Tomcat
Open <TOMCAT_HOME>/conf/server.xml in a text editor with administrator permissions
Add the following block under the<Service>element:
CopyXML
Make sure to change the keystoreFile and the keystorePass attributes according to your settings.
Save the changes to server.xml
Restart Tomcat
This step is only necessary if using the API under HTTPS. In this case you have to make sure that Java can knows about your certificate and can resolve requests to your domain. Add your certificate to Java’s keystore:
Change the alias “collection.mymuseum.org” and the filename “collection-mymuseum-org.crt” according to your files.
JKS: Java KeyStore