Page History

SHRINE utilizes a Java keystore to house certificates to support TLS-based https.

To Generate a New Keystore

To generate a new keystore, run the following command (on one line) within the /opt/shrine/ directory. Please use your own values wherever you see $variables.

Most importantly, ensure that $KEYSTORE_ALIAS matches the publicly-accessible hostname of the machine that will be using this keystore.

$ keytool -genkeypair -keysize 2048 -alias $KEYSTORE_ALIAS -dname "CN=$KEYSTORE_ALIAS, OU=$KEYSTORE_HUMAN, O=SHRINE Network, L=$KEYSTORE_CITY, S=$KEYSTORE_STATE, C=$KEYSTORE_COUNTRY" -keyalg RSA -keypass $KEYSTORE_PASSWORD -storepass $KEYSTORE_PASSWORD -keystore $KEYSTORE_FILE -storetype pkcs12 -validity 7300

For example, a sample site might run this:

$ keytool -genkeypair -keysize 2048 -alias shrine-example.harvard.edu -dname "CN=shrine-example.harvard.edu, OU=SHRINE Example, O=SHRINE Network, L=Boston, S=MA, C=US" -keyalg RSA -keypass password -storepass password -keystore shrine.keystore -storetype pkcs12 -validity 7300

This will generate a shrine.keystore file within the /opt/shrine directory. You can then verify the creation of the keystore by running:

$ keytool -list -keystore shrine.keystore -storepass password

You used keytool to create a new keystore - but you have not yet created any certificates. 

Using a Third-Party-Signed Certificate for Serving https Requests in Tomcat.

This wiki does not attempt to cover any vendor-specific processes or output files, because those can vary over time and across industry. It is up to each remote site that chooses this option to work with its vendor on any necessary technical details.

This guide also assumes the possibility that a site may initially opt for network CA-signed certificate, but later switch over to a third-party certificate. For all examples used in our illustration below this guide uses a fictitious remote site called shrine.example.edu.

First generate a certificate signing request (CSR) using a private key, and to send that CSR to an SSL/TLS vendor such as InCommon or Symantec. This step can be performed using either openssl or keytool. The vendor will in turn generate a certificate for the requested fully-qualified domain name (FQDN), and it may provide additional certificates for its root and intermediate CAs. The remote site should work with the vendor to concatenate all certificates together into one file, so that it would be possible to trace the chain of trust from the endpoint certificate all the way back to the root CA.

Next ensure that the private key that was used to generate the CSR in a separate file. If a utility such as openssl was used to generate the CSR, then a file containing the private key should already be present and this step is unnecessary. If, however, the site used keytool to generate the CSR, then the following commands should be run to extract the private key from the keystore into a separate file. Execute the following commands to extract the private key into a file called private_key.pem (the command below assumes that the keystore is called shrine.keystore):

$ keytool -importkeystore -srckeystore shrine.keystore -srcstorepass <source_keystore_password> -srcalias shrine.example.edu -destalias shrine.example.edu -destkeystore shrine.keystore.p12 -deststoretype PKCS12 -deststorepass <destination_keystore_password>
$ openssl pkcs12 -in shrine.keystore.p12 -nodes -nocerts -out private_key.pem

This private key should be guarded carefully. Ideal places include an encrypted disk volume and non-persistent, RAM-based disk (such as /dev/shm in CentOS or Debian). The key can also be stored in an offline and physically secure location.

...

$ openssl pkcs12 -export -in <certificates_file> -inkey private_key.pem -out shrine.keystore.p12.temp -name shrine.example.edu-https -CAfile <ca_file> -chain -password pass:<your_pkcs12_file_password>

Note here that the value of the -name field is "shrine.example.edu-https". 

The newly constructed PKCS12 file should now be imported into the original shrine.keystore. Execute the following command, and if prompted to overwrite existing entry, answer "yes":

$ keytool -importkeystore -srckeystore shrine.keystore.p12.temp -srcstoretype pkcs12 -srcstorepass <your_pkcs12_file_password> -srcalias shrine.example.edu-https -destkeystore shrine.keystore -deststoretype jks -deststorepass <your_destination_keystore_password> -destalias shrine.example.edu-https

Once the import is completed, your shrine.keystore should now look like this:

Keystore type: jks
Keystore provider: SUN

Your keystore contains 1 entry
shrine.example.edu-https, Jul 31, 2019, PrivateKeyEntry, 
Certificate fingerprint (SHA1): EF:AF:5E:D3:1A:97:AA:F2:6D:50:B8:9A:23:98:B5:2C:0C:18:C3:4B

Next, configure the alias entry in Tomcat's server.xml to point to the newly imported, third-party-generated certificate:

<Connector port="6443" protocol="org.apache.coyote.http11.Http11NioProtocol"
               maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS"
               keystoreFile="/opt/shrine/shrine.keystore"
               keystorePass="xxxxxxxxxx"
               keyAlias="shrine.example.edu-https"/>

Once all configuration files have been updated, restart Tomcat. If everything has been configured properly, you should no longer see any warning messages from your browser regarding untrusted certificates when accessing your SHRINE host.

Here's a sample server.xml file (note the 'Connector port = "6443"' section):

...

...

Always use encrypted communication for all http connections in SHRINE networks. SHRINE carries login information in http headers. I2b2 carries similar information in http request bodies.

Standard TLS-based https is sufficient.

Setting up SHRINE's Keystore in versions 3.2 and earlier was much more complex. Now SHRINE uses Tomcat's TLS-based https the way almost all other applications do. Tomcat's own documentation is insufficient but these instructions were clear .