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 recommended that SHRINE networks going forward adopt this approach whenever 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.

For Hub Administrators

The server that will function as the Certificate Authority will require a distribution of OpenSSL with the CA.sh/CA.pl/CA helper script. While it is possible to operate as a CA without the helper script, it is strongly recommended to use the helper script, as it makes life much easier. The exact location of this helper script varies from distribution to distribution, but three places to start are /usr/local/ssl/misc, /etc/pki/tls/misc, and /System/Library/OpenSSL/misc. The latter of these two is what CentOS uses, and the rest of the guide will be written assuming a CentOS environment.

...

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

...

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

...

/opt/shrine/tomcat/bin/shutdown.sh && /opt/shrine/tomcat/bin/startup.sh