This wiki page has been hidden from the rest of the SHRINE documentation due to several problems and inaccuracies that require significant revision:
The solution to problems #2 and #3 is:
This page should be rewritten before it is activated again. I have made the recommendation above based on actual tests I conducted this afternoon (2020-May-15) using OpenJDK 11.0.7. |
By default, our recommendation for a typical ACT remote site is to have it submit a Certificate Signing Request (CSR) to the certificate authority (CA) of the ACT tier to which they are joining. The CA will in turn generate a new certificate for the downstream site, and we will return that certificate, the hub certificate, and the CA certificate of the tier back to the downstream site. The site will then import the certificates into their shrine keystore file, and configure their shrine.conf
and server.xml
to point to the alias entry in the keystore that corresponds to the site.
A typical keystore after importing all the certs in would look like this (assuming that the downstream site is called "acttest.harvardshrine.net
"):
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
would contain a block 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
would contain a block 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"/> |
One drawback when using the above approach is that a web browser attempting to access a shrine host whose certificates have been configured this way will generate a warning. The reason for the warning is that the CA that is used to generate the downstream certificate is not recognized by default as a trusted CA. Consequently, any certificate that the CA signs is not accorded with trust by the browser. While the browser can be configured to ignore the warning and the CA can be manually imported into the browser's trust store, some downstream sites may opt for a more elegant approach.
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):
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!
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: