Repository cluster keys

A cluster key serves as an identifier for a distributed object repository. This is the signing key that signs the certificates of all nodes in the object repository. It's analogous to a certificate authority.

The --name parameter is required. It specifies a name for the object repository. The object repository server uses this name to register itself with the system portmapper. The name must comply with the naming convention for portmapper registrations: basically the name must look like a domain name. The actual domain name does not actually need to exist, as long as it falls within a valid governing domain. For example, when example.com organization's policy assigns “objrepo.example.com” for its object repositories:

The other parameters are optional: --bits specifies the bit strength of the signing key, “weak”, “low”, “normal” (default), “high”, or “ultra”; --digest specifies the signing algorithm, the default is “sha256”; and --expires specifies the certificate's duration (default is “5 years”), this parameter understands “n days”, “n months”, and “n years”; --type specifies the certificate type, either “rsa” (default) or “dsa”.

The given directory gets created for the new cluster key, with group and world permissions turned off, and the new cluster certificate and key gets saved there. The cluster key directory must be kept secure, and should exist on a machine that runs (or will run) one of the nodes in the cluster repository. It does not need to be copied to every node's machine.

If not specified, directory gets defaulted to @localstatedir@/stasher/clusters/name, where name is the specified cluster name.

Repository cluster keys sign individual repository node keys, which have a shorter expiration interval. Node keys must expire before the cluster key that signed them.

Before an existing cluster key expires, a new repository cluster key gets generated by running the same command, and pointing it to an existing cluster key directory. The --name parameter is not needed for the new key, the cluster name remains the same, and it's retrieved from the existing key in the directory (if --name is specified it must give the same name). The new key gets gets added to the directory. The existing, expiring key remains valid until it actually expires.

New keys must always have the same name, but other parameters can be different.

--list produces a formatted output, listing the keys in the specified cluster key directory, and their expiration. The Key ID column contains each key's identifier.

If desired, multiple keys may be installed in a cluster directory, and used concurrently, for reasons other than expiration. All keys are interchangable with each other, any valid key can be used to create and sign individual cluster node keys.

After a cluster key expires, it should be removed from the cluster key directory, but it may be removed for other reasons, as long as there are no installed node certificates that are signed by that key.

After creating a new cluster key, or after removing a key, the updated list of cluster certificates needs to be exported, or pushed, into the repository:

nodekeydirectory is the directory of an existing cluster node, on the same machine. If the node is up, and the cluster is in quorum, the updated list of cluster certificates from directory gets distributed to all nodes in the cluster. If the node is not running, the updated cluster certificate list gets distributed when the node comes up and joins a cluster that's in quorum.

Do not export cluster keys to a running node that's not connected to a cluster, or if the cluster is not in quorum (the majority of nodes in the cluster are up, connected and synchronized with each other).

Repository node keys

Each node in a cluster has its own key. The key gets signed by the object repository's cluster key. A node can connect to other nodes in the cluster only if both node's keys are mutually signed by a cluster key.

The --name parameter gives the name of the node in the object repository cluster. This is a label. Each node in the repository must have a unique label. The label gets prepended to the signing cluster's key, and when the node starts, the resulting name gets registered with the portmapper. This allows multiple nodes in the cluster to run on the same machine, presumably for testing purposes.

The other parameters are optional: --bits specifies the bit strength of the signing key, “weak”, “low”, “normal” (default), “high”, or “ultra”; --digest specifies the signing algorithm, the default is “sha256”; and --expires specifies the certificate's duration (default is “1 year”), this parameter understands “n days”, “n months”, and “n years”.

The new node certificate and key gets installed in the specified. nodekeydirectory, which gets created if it does not exist. The new node certificate gets signed with the newest cluster key from the cluster key directory, if there's more than one there. --signkey selects a non-default key instead, if specified.

nodekeydirectory is optional. If this command has two directory parameters, the first parameters is the new node key directory and the second parameter is the cluster key directory. If this command has a single directory parameter, it specifies a cluster key directory, and the node key directory defaults to @localstatedir@/stasher/newnodes/name, where name is the new node's name.

A node certificate must be kept secure, just like a cluster certificate. The certificate file gets created without group and world permissions, but the new node directory is world readable. This allows processes running under any userid to connect to the local object repository node, which can read the certificate.

This command also copies the current list of cluster certificates into the created new node directory. As previously described, updates to the list of cluster certificates are distributed by --export, using any existing node in the object repository cluster.

The new node key directory gets created on the same machine as the cluster key directory, since a node key must be signed by a cluster key. To install nodes on other machines, copy the created node key directory, securely, to the other machine, taking care to preserve the structure and the permissions of all the contents of the newly-created node key directory.

A node certificate expires just like cluster certificates, and a new node certificate, with the same name must be created, before the existing node certificate expires.

A renewal certificate gets created by specifying an existing nodekeydirectory. --name default's to the node's name. A renewal certificate for another node gets created by an explicit --name. In that case, both the node on this machine and the node whose certificate is getting renewed must be up and connected to the cluster. The node running on this machine forwards the certificate to the peer specified by --name, which installs it.