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 likewise problematic in that it is evoking an alias where no such alias 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
- Require a source alias and a destination alias when importing the PKCS12 file into the keystore, OR
- 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 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, by default, the browser does not trust the CA that is used to generate the downstream certificate, because none of the ACT CAs are public. Consequently, any certificate that the CA signs is not trusted 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. Indeed, the option of using a third-party-signed certificate provides a more seamless user experience in the web browser, because the root and intermediate CAs are already trusted by the browser.
This wiki page describes the process of using a third-party-signed certificate for the purpose of encrypting web browser traffic. It is important to note that a third-party certificate does not replace the ACT-signed certificate entirely, because the ACT certificate is still required for signing all application-specific messages. Also, this wiki does not attempt to cover any vendor-specific processes or output files, because those can vary over time. 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 ACT-signed certificate, but later switch over to a third-party certificate.
The first step is to generate a certificate signing request (CSR) using a private key, and to send that CSR to an SSL/TLS vendor. This step can be performed using either openssl or keytool. The vendor will in turn provide 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, such that it would be possible to trace the chain of trust from the endpoint certificate all the way back to the root CA.
The next step is to extract the private key that was used to generate the CSR. 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 using a private key from a store called shrine.keystore, then the following commands should be run to extract the private key into a separate file. Execute the following commands to extract the private key into a file called private_key.pem:
$ keytool -importkeystore -srckeystore shrine.keystore -srcstorepass <source_keystore_password> -srcalias <source_alias> -destalias <destination_alias> -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).
Now combine the private key with the chained cert into a PKCS12 package (.pfx or .p12 suffix) that will set the stage to import the bundle into the final keystore. The most important concept about using a third-party certificate is that we must construct a chain of trust that an application such as SHRINE can trace from the endpoint certificate all the way back to the root CA. Without this trust tracing, SHRINE will report that it is unable to proceed. In light of this important idea, in the following command (again, assuming that the private key file is called private_key.pem), the certificates_file contains the new certificate plus all intermediate certificates plus the root certificate, and the ca_certificate contains the intermediate certificates plus the root certificate. Run this command to bundle the private key, the endpoint certificate, and all intermediate and root certificates into one single entry within the PKCS12 store:
$ openssl pkcs12 -export -in <certificates_file> -inkey private_key.pem -out <pkcs12_file> -name <source_entry_alias> -CAfile <ca_certificate> -chain -password pass:<password>
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:
Overview
Content Tools