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

...

mv newcert.pem shrine-client-signed.pem

For

...

All Other Nodes

The site node administrator will require the Java keytool, which should already be included on a SHRINE-capable machine.

...

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.pemcrt -keystore $KEYSTORE_FILE -storepass $KEYSTORE_PASSWORD
keytool -import -v -alias $KEYSTORE_ALIASshrine-hub-https -file shrine-clienthub-signedhttps.pemcrt -keystore $KEYSTORE_FILE -storepass $KEYSTORE_PASSWORD
keytool -keypass $KEYSTORE_PASSWORD -import -v -alias $KEYSTORE_ALIAS -file shrine-client-signed.crt -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. This is the signed certificate from the Hub (signed from the CSR). 
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

...

Serve https

It is often fine to serve https using your own private key entry. However, if the CA is not signed by a certificate authority recognized by your users' browsers then they will have to click through warnings to use SHRINE. Also, some institutions may prefer SHRINE nodes to use different certificates to serve https. It is perfectly fine to import an extra cert into the keystore to serve https, but you should inform the hub admin of changes in advance. Your adapter will not run queries until the hub trusts your new cert, but the hub admin can harvest the public side of the cert using openssl.

Configure tomcat to serve https via its server.xml file:

<Connector port="{{ shrine_ports.https }}" protocol="org.apache.coyote.http11.Http11NioProtocol"
               maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS"
               keystoreFile="{{ tomcat_keystore_path }}"
               keystorePass="{{ tomcat_keystore_password }}"
               keyAlias="{{ tomcat_keystore_alias }}" />

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"
  }
}

In all cases, add the caCertAliases option into the keystore block, and make sure that the values for privateKeyAlias and password are also set appropriately. privateKeyAlias should be the same as $KEYSTORE_ALIAS. Also note that caCertAliases is an a json array of values. Do NOT surround it in only quotation marks, square brackets must be used. The value should match the alias of the -ca cert imported earlier. If using the ssl_keytool.sh script to import, the alias will automatically be set to the filename of the cert file.

keystore {
  [...]
  caCertAliases = ["shrine-hub-ca.pem"] 
  [...]
}

Save these changes and restart SHRINE. Assuming all passwords and other values are set appropriately, SHRINE should start up successfully, and it will now trust incoming queries from any node that attaches the CA certificate to their query signature.

...