# HTTPS Setup

The process consists of these steps:

1. [Choose the protocol](#usingtls-httpswithemuseum-chooseprotocol) to be used by Tomcat
2. Create a keypair which consists of a private key and a certificate, and [create a Certificate Signing Request](#usingtls-httpswithemuseum-createcertificateandcertificatesingingrequest) (CSR) that includes the certificate
3. Send the CSR to a Certificate Authority (CA) to [obtain a signed certificate](#usingtls-httpswithemuseum-obtainsignedcertificate)
4. [Create a keystore](#usingtls-httpswithemuseum-createkeystore) that includes both the private key and the signed certificate
5. [Configure Tomcat](#usingtls-httpswithemuseum-configuretomcat) to enable HTTPS and use the Keystore

### Choose Protocol <a href="#usingtls-httpswithemuseum-chooseprotocol" id="usingtls-httpswithemuseum-chooseprotocol"></a>

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 <a href="#usingtls-httpswithemuseum-apr-native" id="usingtls-httpswithemuseum-apr-native"></a>

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 <a href="#usingtls-httpswithemuseum-nio" id="usingtls-httpswithemuseum-nio"></a>

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 <a href="#usingtls-httpswithemuseum-createcertificateandcertificatesingingrequest" id="usingtls-httpswithemuseum-createcertificateandcertificatesingingrequest"></a>

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 <a href="#usingtls-httpswithemuseum-openssl" id="usingtls-httpswithemuseum-openssl"></a>

* Install [OpenSSL](https://www.openssl.org/) (or download the [OpenSSL binaries](http://downloads.sourceforge.net/gnuwin32/openssl-0.9.8h-1-bin.zip))<br>
  * 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)\
    \&#xNAN;*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 <a href="#usingtls-httpswithemuseum-keystoreexplorer" id="usingtls-httpswithemuseum-keystoreexplorer"></a>

* Download and install the [KeyStore Explorer](http://keystore-explorer.org/) 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\
      \&#xNAN;*The validity period determines how long the certificate will be valid for*
  * Click the @ icon
  * Enter the requested information\
    \&#xNAN;*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 <a href="#usingtls-httpswithemuseum-obtainsignedcertificate" id="usingtls-httpswithemuseum-obtainsignedcertificate"></a>

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 <a href="#usingtls-httpswithemuseum-createkeystore" id="usingtls-httpswithemuseum-createkeystore"></a>

#### PKCS #12 <a href="#usingtls-httpswithemuseum-pkcs-12" id="usingtls-httpswithemuseum-pkcs-12"></a>

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.&#x20;

#### JKS <a href="#usingtls-httpswithemuseum-jks" id="usingtls-httpswithemuseum-jks"></a>

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\
  \&#xNAN;*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.&#x20;

### Configure Tomcat <a href="#usingtls-httpswithemuseum-configuretomcat" id="usingtls-httpswithemuseum-configuretomcat"></a>

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 <a href="#usingtls-httpswithemuseum-apr-native.1" id="usingtls-httpswithemuseum-apr-native.1"></a>

* 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:\ <br>

  ```xml
  <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

  ```xml
  <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 <a href="#usingtls-httpswithemuseum-nio.1" id="usingtls-httpswithemuseum-nio.1"></a>

* Open `<TOMCAT_HOME>/conf/server.xml`  in a text editor with administrator permissions
* Add the following block under the`<Service>`element:\ <br>

  ```xml
  <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 <a href="#usingtls-httpswithemuseum-configurejava" id="usingtls-httpswithemuseum-configurejava"></a>

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 <a href="#usingtls-httpswithemuseum-termsandabbreviations" id="usingtls-httpswithemuseum-termsandabbreviations"></a>

* CA: [Certificate Authority](https://www.wikipedia.org/wiki/Certificate_authority)
* CSR: [Certificate Signing Request](http://wikipedia.org/wiki/Certificate_signing_request)
* JKS: [Java KeyStore](https://wikipedia.org/wiki/Keystore)
* RSA: [Rivest-Shamir-Adleman cryptosystem](https://wikipedia.org/wiki/RSA_\(cryptosystem\))
* PKCS: [Public Key Cryptography Standards](https://wikipedia.org/wiki/PKCS)