Overview
Have an Idea? Contact Support Go to Prism docs
Choose a Product

HTTPS Setup

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:

  1. Choose the protocol to be used by Tomcat

  2. Create a keypair which consists of a private key and a certificate, and create a Certificate Signing Request (CSR) that includes the certificate

  3. Send the CSR to a Certificate Authority (CA) to obtain a signed certificate

  4. Create a keystore that includes both the private key and the signed certificate

  5. Configure Tomcat to enable HTTPS and use the Keystore

Choose Protocol

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.

APR/native

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.

NIO

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.

Create Certificate and Certificate Signing Request

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).

OpenSSL

  • 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:

      SET PATH=%PATH%;C:\eMuseum\openssl-0.9.8h-1-bin\bin
SET OPENSSL_CONF=C:\eMuseum\openssl-0.9.8h-1-bin\share\openssl.cnf

  • Create a private key by running the following command in a command prompt:

    openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out collections-mymuseum-org.key

    (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:

    openssl req -new -key collections-mymuseum-org-key.pem -out collections-mymuseum-org.csr

    (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.

Keystore Explorer

  • 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

Obtain Signed Certificate

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.

Create Keystore

PKCS #12

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.

JKS

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.

Configure Tomcat

Depending on the protocol, the configuration is slightly different. In both cases, copy the (Keystore) file(s) to the <TOMCAT_HOME>/conf/ folder.

APR/native

  • 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: 

    <Connector port="443" protocol="org.apache.coyote.http11.Http11AprProtocol" maxThreads="150" SSLEnabled="true">
    <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
    <SSLHostConfig>
        <Certificate
            certificateKeyFile="conf/collections-mymuseum-org.key"
            certificateFile="conf/collections-mymuseum-org.crt"
            certificateChainFile="conf/cachain.crt"
            type="RSA"
        />
    </SSLHostConfig>
</Connector>

    CopyXML

  • For Tomcat 8 and below add the following block under the <Server> element:i

    <Connector
    protocol="org.apache.coyote.http11.Http11AprProtocol"
    port="443"
    maxThreads="200"
    scheme="https"
    secure="true"
    SSLEnabled="true"
    SSLCertificateFile="conf/collections-mymuseum-org.crt"
    SSLCertificateKeyFile="conf/collections-mymuseum-org.key"
    SSLVerifyClient="optional"
    SSLProtocol="TLSv1.1+TLSv1.2"
/>

    CopyXML

  • Save the changes to server.xml

  • Restart Tomcat

NIO

  • Open <TOMCAT_HOME>/conf/server.xml in a text editor with administrator permissions

  • Add the following block under the<Service>element: 

    <Connector
    port="443"
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    maxThreads="150"
    SSLEnabled="true"
    scheme="https"
    secure="true"
    clientAuth="false"
    sslProtocol="TLS"
    keystoreFile="C:\Tomcat\collection.mymuseum.org.jks"
    keystoreType="JKS"
    keystorePass="yourkeystorepassword"
/>

    CopyXML

    Make sure to change the keystoreFile and the keystorePass attributes according to your settings.

  • Save the changes to server.xml

  • Restart Tomcat

Configure Java

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:

keytool -keystore cacerts -import -alias collection.mymuseum.org -file collection-mymuseum-org.crt

Change the alias “collection.mymuseum.org” and the filename “collection-mymuseum-org.crt” according to your files.

Terms and Abbreviations

PreviousUpgrade GuideNextKnowledge Base Articles

Last updated