Versions Compared

Old Version 45

changes.mady.by.user Simon Chang

Saved on

compared with

New Version Current

changes.mady.by.user Simon Chang

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info
titleCAUTION

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

  1. 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.
  2. 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.
  3. 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:

  1. 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 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.

...

Next, upon receiving the signed certificate from the third-party CA, the remote site should then bundle the private key with the chained certificates into a PKCS12 file (.pfx or .p12 suffix) so that SHRINE can verify the chain of trust from the endpoint certificate all the way back to the root CA.  Without this trust verification, SHRINE will be unable to use the certificates as intended.  For our purpose, the PKCS#12 file format is ideal because it can combine a private key with all corresponding chained certificates into a single entry in the file, and because the format is accessible by both openssl and keytool.  In the following command (again, assuming that the private key file is called private_key.pem), the certificates_file contains the new endpoint certificate plus all intermediate certificates plus the root certificate, and the ca_file contains only 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:

...

Code Block
languagexml
themerdark
<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="xxxxxxxxxxxxxxxx"
               keyAlias="shrine.example.edu-https"/>


Once that change is madeall configuration files have been updated, restart Tomcat. When finished, confirm that the newly installed certificate is being used by using your web browser to navigate to your SHRINE host.                      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.