Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Using Multiple Root Certificates

      +
      Couchbase Server supports use of multiple CA (or 'root') certificates, for a single cluster.

      Benefits

      Prior to Couchbase Server Version 7.1, a Couchbase-Server cluster could maintain at most one root certificate: all nodes and all clients were obliged to rely on this certificate’s authority. From version 7.1, Couchbase Server permits multiple root certificates to be maintained in a trust store for the cluster. This allows an individual node either to use a CA that is also used by one or more other nodes; or to use a CA that is used by no other node. This may be used during CA certificate rotation: a new CA is uploaded, node certificates are changed one by one, and finally, the old CA is removed.

      Couchbase Server additionally uses its list of trusted certificates to verify:

      • Client certificates (when client certificate authentication is enabled: for information, see Enable Client-Certificate Handling).

      • The identities of cluster nodes (when node-to-node encryption is enabled: for information, see Manage Node-to-Node Encryption).

      • The identities of nodes that join the cluster (when the server has been provisioned with certificates).

      • The identity of LDAP servers (when TLS has been turned on, in the LDAP settings: for information, see LDAP Host Configuration).

      Illustration

      A cluster-configuration that uses multiple CAs is illustrated as follows:

      clusterWithCerts

      The diagram assumes that certificate-based client authentication has been activated.

      The annotations are as follows:

      1. A Couchbase-Server cluster is configured with four nodes, access to each of which is certificate-protected.

      2. The trust store for the cluster contains ten CAs, which are CA a to CA j. Of these, three root CAs have been used in the signing of individual node-certificates: these are CA a, CA e, and CA g.

      3. The node-certificate for Node 1 is signed by an intermediate certificate, which has itself been signed by the root certificate CA a.

      4. The node-certificate for Node 2 is signed by an intermediate certificate, which, like the intermediate certificate used by Node 1, has itself been signed by the root certificate CA a.

      5. The node-certificate for Node 3 has been directly signed by the root certificate CA e.

      6. The node-certificate for Node 4 has been signed by a chain of two intermediate certificates, the highest in the chain having itself been signed by the root CA, CA g.

      7. The certificate for Client 1 has been signed by an intermediate certificate, which has been directly signed by the root certificate CA a: this is the CA providing authority to Node 1 and Node 2. This allows mutual authentication to proceed between Node 1 and Client 1, since the certificate of each takes its authority from CA a. (Note that this is the only form of certificate-based authentication that was supported by Couchbase Server, prior to version 7.1.)

      8. The certificate for Client 2 has been directly signed by the root certificate CA h. Client 2 also maintains the root certificate CA a in its trust store. This allows mutual authentication to proceed between Node 2 and Client 2; since Client 2 recognizes the authority of CA a, and Node 1 recognizes the authority of CA h. In each case, the recognized root CA exists in the entity’s trust store, but has not played a role in the signing of the entity’s own certificate.

      9. The certificate for Client 3 has been signed by an intermediate certificate, which has itself been signed by the root certificate CA k. Client 3 also maintains CA e in its trust store. This prevents mutual authentication from occurring between Client 3 and Node 3: although the certificate for Node 3 acquires its authority from CA e, which is in the client’s trust store, and is thus recognized by the client; the client’s certificate is signed by CA k, which is not in the cluster’s trust store, and is therefore not recognized by the cluster.

      10. The certificate for Client 4 is directly signed by CA c. The client’s trust store also contains CA e and CA g. This allows mutual authentication to succeed between Client 4 and Node 3, since the authority of each is derived from a root certificate in its opposite’s trust store. This also allows mutual authentication to succeed between Client 4 and Node 4, for the same reason.

      Clusters Running Multiple Couchbase-Server Versions

      Multiple CAs are supported by Couchbase Server Version 7.1 and later. Typically, when a cluster is upgraded, it temporarily includes nodes of two versions; one being the version to which the cluster is being upgraded, the other the version from which it is being upgraded.

      Once the cluster’s nodes are all upgraded to version 7.1 or later, multiple CAs are fully supported. During the upgrade period, only some of the supportive APIs can be used: for information, see Certificate Management API.

      Adding Nodes

      When a new node is added to a Couchbase-Server cluster that is version 7.1 or later, the new node may be added with its existing root certificate and corresponding certificate chain, provided that the root certificate is already included in the cluster’s trust store: if the node’s certificate has not been added to the trust store, an error is flagged.

      The trust store of a new node is used when initial connection is being established with the cluster that is being joined: then, during the process whereby the new node is added to the cluster, the trust store of the new node is overwritten with the cluster’s trust store.

      For example, assume the existence of the following:

      • A cluster whose trust store contains CA 1, CA 2, and CA 3; and whose node 1 authenticates with Cert 1, which is signed by CA 1.

      • A separate, individual node, node x, whose trust store contains CA 1, CA 2, and CA 4; and which authenticates with Cert 2, which is signed by CA 2.

      After node x has been added to the cluster, the trust store of node x contains only the root certificates for the cluster (which are indeed CA 1, CA 2, and CA 3): it no longer contains CA 4.

      Note also that if the node certificate for node x, Cert 2, had been signed by CA 4 (instead of CA 2), the addition of node x would fail; because the cluster does not trust CA 4.

      Adding Intermediate Certificates to the Trust Store

      Intermediate Certificates can also be uploaded to the cluster’s trust store.

      In versions of Couchbase Server prior to 7.1, as described in Intermediate Certificates and Node Certificates (and as exemplified in Configure Server Certificates), a node certificate references its CA by presenting, to the client, as the file chain.pem, all certificates whose signature-chain leads to that CA. Likewise, a client references its own CA by presenting, to the server, all certificates whose signature-chain leads to its own CA.

      This way of mutually referencing CAs continues to be supported in 7.1+. Alternatively, however, the intermediate certificates in the chain need not be presented — their existing presence in the recipient’s trust store being assumed instead. For example:

      • When the node’s chain contains one or more intermediate certificates, and the node presents only its node certificate (as the file chain.pem) to the client; if the client can locate those intermediate certificates and their corresponding CA in the client’s trust store, authentication of the node can proceed.

      • When the client’s chain contains one or more intermediate certificates, and the client presents only its client certificate to the node; if Couchbase Server can locate those intermediate certificates and their corresponding CA in the Couchbase-Server trust store, authentication of the client can proceed.

      Also supported are cases where some but not all of a chain’s intermediates are directly presented, and the rest are available in the trust store of the recipient.

      For an example, see Deploying an Intermediate Certificate via Trust Store.