Page History

...

In order to reduce administrative overhead in larger hub-and-spoke SHRINE topologies, SHRINE will support using certificates signed by a central Certificate Authority (CA) starting with SHRINE 1.18. Using this approach, a SHRINE network will establish its own private CA (typically administered by the hub administrator), and sites generate certificate signing requests that will be signed by this CA. A SHRINE node then adds this new CA-signed certificate and the CA's own certificate to their keystore, and then adds a few values to shrine.conf. Now, instead of having to import the certificate of every other site on the network along with the hub's certificate, a site only needs to import the hub's CA certificate. If the site receives a query from another node that has been blessed by the same CA, SHRINE will trust that query. This moves the trust model from each individual site to the hub (and thus, the network as a whole), making it easier to add additional nodes to the network later on.

We highly recommend that It is highly recommended that SHRINE networks going forward adopt this approach regardless of network sizewhenever possible, especially for networks larger than 4 nodes. When using a CA in a hub-based topology, a node only needs to create firewall exceptions for one other host (the hub) and only needs to perform one certificate exchange, solving the N^2 problem that has traditionally afflicted larger SHRINE networks.

...

The script will ask for a password, which you will be prompted for whenever accessing the private key. Keep this password safe and secure. Additionally, in typical SHRINE setups that do not differentiate between HTTPS and SHRINE signing certificates, the password for this private key must be the same as the password used for the keystore ($KEYSTORE_PASSWORD).

...

Ensure that all environment variables in shrine.rc are set properly, as these are the values that will be used to generate the certificate information. Most importantly, ensure that $KEYSTORE_ALIAS matches the publicly-accessible hostname of the machine that will be using this keystore. To generate a new keystore, run the following command:

...

Or, for a more convenient method, copy the ssl_keytool.sh script from the SHRINE installer and run the following command instead:

...

After the hub administrator (or CA administrator, if the two entities are separate) approves and signs the certificate, they will send back a signed version of your cert along with the hub's CA cert, as well as the cert used for normal HTTPS communication with the hub. Import all of these into your keystore with the following commands in order:

keytool -import -v -alias shrine-hub-ca -file shrine-hub-ca.pem -keystore $KEYSTORE_FILE -storepass $KEYSTORE_PASSWORD
keytool -import -v -alias $KEYSTORE_ALIASshrine-hub-https -file shrine-clienthub-signedhttps.pem -keystore $KEYSTORE_FILE -storepass $KEYSTORE_PASSWORD
keytool -import -keypassv -alias $KEYSTORE_PASSWORD -ALIAS -file shrine-client-signed.pem -keystore $KEYSTORE_FILE -storepass $KEYSTORE_PASSWORD -keypass $KEYSTORE_PASSWORD -trustcacerts

Make absolutely sure the -alias value in the  final third and final command exactly matches the alias used for your original certificate! (the one marked as PrivateKeyEntry in the keystore) Otherwise, queries will fail with signature verification errors, since the CA's signature will not be on the exact same keystore entry that SHRINE uses. Upon importing your signed certificate, the following message should appear:

...

After a successful round of imports, verify the contents of the keystore with keytool -list -v -keystore $KEYSTORE_FILE. There should be at 2 least 3 entries in the keystore:

1. Your own PrivateKeyEntry, with an additional certificate chained to it. The "Issuer:" line should reflect information from the hub's CA, not your own.
2. The hub's HTTPS certificate.
3. The hub's CA signature certificate. The "Owner:" line on this should match the "Issuer:" line on your PrivateKeyEntry's certificate.

In versions before 1.22, you could also include the https cert in the same keystore. 1.22.4 and onward requires a separate keystore for https, with a cert signed by a public CA.

keytool -import -v -alias shrine-hub-https -file shrine-hub-https.pem -keystore $HTTPS_KEYSTORE_FILE -storepass $KEYSTORE_PASSWORD

Update shrine.conf and Restart SHRINE

Update shrine.conf and Restart SHRINE

Prior to 1.22.4 -  if If the node is a Query Entry Point, add the attachSigningCert option into the queryEntryPoint block, and make sure the broadcasterServiceEndpoint.url value points at the appropriate hub.

queryEntryPoint {
  [...]
  attachSigningCert = true 
  [...]
  broadcasterServiceEndpoint {
    url = "https://shrine-hub.u-of-example.edu:6443/shrine/rest/broadcaster/broadcast"
  }
}

...