Switching from a hub-signed (self-signed) certificate to a commercial SSL cert

CAUTION

This wiki page has been hidden from the rest of the SHRINE documentation due to several problems and inaccuracies that require significant revision:

We should avoid using a real-life example of a third-party SSL/TLS provider, principally because different providers use different terminologies that may confuse remote sites. I have also come across conflicting instructions on building a certificate chain (namely, that the order in which the certificates appear in such a file does and does not matter). I have also seen in my actual tests that keytool has not consistently processed such concatenated files. We should therefore ask the downstream sites to refer to their provider's instructions instead of presuming that a generic set of instructions is sufficient for all or even most use cases.
The original command to construct a PKCS12 file using the private key and its public certificate(s) does not actually define an alias for the entry in the file. As a result, when the succeeding command is run to import the file into a keystore, the user is unaware that the default alias for the entry is "1" (numerical one), and therefore the import will fail.
The command to import the PKCS12 file into the keystore is problematic in that it is evoking an alias where none existed in the PKCS12 file (see previous problem). As a result, the command as it stands in the overall sequence will fail when executed.

The solution to problems #2 and #3 is:

Require an explicit name for the alias in the PKCS12 file generation step, and then either
1. Require a source alias and a destination alias when importing the PKCS12 file into the keystore, OR
2. Omit all mentions of alias when importing, essentially turning the command into a keystore-to-keystore import.

This page should be rewritten before it is activated again. I have based the recommended solution above based on actual tests I conducted this afternoon (2020-May-15) using OpenJDK 11.0.7.

PLEASE NOTE

Note that the following instructions are for a Comodo PositiveSSL certificate / bundle. This process should be similar to other commercial SSL providers.

In recent times, our recommendation for all network downstream sites is to have them submit a Certificate Signing Request (CSR) to the Hub for signing, in which a signed certificate is then sent back along with the Hub's CA and HTTPS certificate. Sites then import the certs into their shrine.keystore and configure shrine.conf and server.xml to look at that keystore to serve SHRINE.

A typical keystore after importing all the certs in would look like this:

Keystore type: jks
Keystore provider: SUN

Your keystore contains 3 entries

acttest.harvardshrine.net, Oct 31, 2018, PrivateKeyEntry, 
Certificate fingerprint (SHA1): 26:0B:FE:98:21:BA:C8:5A:A5:F5:35:79:8E:81:1A:E9:F4:3B:FF:56

shrine-act-test-ca, Jul 31, 2019, trustedCertEntry, 
Certificate fingerprint (SHA1): 13:4D:B5:5C:E3:48:A0:7B:9B:20:22:8B:0B:C1:BE:DD:B9:E4:1B:AD

shrine-act-test.hms.harvard.edu, Jul 31, 2019, trustedCertEntry, 
Certificate fingerprint (SHA1): 52:82:A0:6D:D1:48:B2:EA:BB:2C:58:BD:E5:C7:3B:21:75:2B:46:F6

Their shrine.conf keystore block would look like this:

keystore {
    file = "/opt/shrine/shrine.keystore"
    password = "xxxxxx"
    privateKeyAlias = "acttest.harvardshrine.net"
    keyStoreType = "JKS"
    caCertAliases = ["shrine-act-test-ca"]
  }

And their server.xml 6443 Connector block would look like this:

<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="xxxxxx"
               keyAlias="acttest.harvardshrine.net"/>

The problem with this is that when you start Tomcat and then navigate to the SHRINE login page, you're greeted with a browser exception warning. This warning is because the CSR that the HUB CA signed is not a publicly recognized CA, therefore it's treated like a "self-signed" certificate. The end-user will then need to click through the warning to add an exception to the site. This can get taxing for larger institutions and will be tedious for each user.

So, a solution for this is to utilize a commercial SSL cert to serve the SHRINE application through Tomcat. You will need to create a CSR from your existing shrine.keystore to send to the commercial provider to get a SSL cert back. For example, ComodoSSL will send back 4 certificates (after sending them the CSR):

AddTrustExternalCARoot.crt
SectigoRSADomainValidationSecureServerCA.crt
USERTrustRSAAddTrustCA.crt
acttest_harvardshrine_net.crt

First, you'll need to bundle up the certs into a chained cert. It's important to add these certs in the correct order, which you can discern from getting the details from each cert. Each cert will refer to the next level cert. Typically, you'll be adding the domain cert + intermediate 2 + intermediate 1 + root.

cat acttest_harvardshrine_net.crt SectigoRSADomainValidationSecureServerCA.crt USERTrustRSAAddTrustCA.crt AddTrustExternalCARoot.crt > chain.crt

After you have created the chained cert, you will now need to extract the private key from the shrine.keystore that you had initially created:

openssl pkcs12 -in shrine.keystore -nodes -nocerts -out private_key.pem

Keep this private key safe in a secure directory!

For generated private keys

NOTE: If you had previously generated your own private key to acquire the commercial SSL cert, you can use that private key for the next steps, as the private key extracted from the shrine.keystore will not match the private key in the commercial SSL cert.

Next, once you have the private key, you'll need to combine the chained cert and the private key into a PKCS12 package (.pfx) in order to import back into the shrine.keystore:

openssl pkcs12 -export -in chain.crt -inkey private_key.pem -out chain.pfx

Once you have the PKCS12 package, you'll now need to import this into your existing shrine.keystore:

keytool -importkeystore -deststorepass xxxxxx -destkeystore shrine.keystore -srckeystore chain.pfx -srcstoretype PKCS12 -alias acttest.harvardshrine.net-https

Once imported in, your shrine.keystore should look like this:

Keystore type: jks
Keystore provider: SUN


Your keystore contains 4 entries
acttest.harvardshrine.net, Oct 31, 2018, PrivateKeyEntry, 
Certificate fingerprint (SHA1): 26:0B:FE:98:21:BA:C8:5A:A5:F5:35:79:8E:81:1A:E9:F4:3B:FF:56

acttest.harvardshrine.net-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

shrine-act-test-ca, Jul 31, 2019, trustedCertEntry, 
Certificate fingerprint (SHA1): 13:4D:B5:5C:E3:48:A0:7B:9B:20:22:8B:0B:C1:BE:DD:B9:E4:1B:AD

shrine-act-test.hms.harvard.edu, Jul 31, 2019, trustedCertEntry, 
Certificate fingerprint (SHA1): 52:82:A0:6D:D1:48:B2:EA:BB:2C:58:BD:E5:C7:3B:21:75:2B:46:F6

Now, keeping everything the same in shrine.conf, you will need to switch the alias entry in Tomcat's server.xml to point to the newly imported certificate package:

<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="xxxxxx"
               keyAlias="acttest.harvardshrine.net-https"/>

Once that change is made, you will need to restart Tomcat services. Once things are back up, you should see a valid certificate ("lock") when you navigate to the SHRINE application:

Page tree

Switching from a hub-signed (self-signed) certificate to a commercial SSL cert