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

Certificates

      +
      Couchbase Server supports x.509 certificates for client and server.

      Certificates and Couchbase Server

      Couchbase Server supports the use of x.509 certificates, for clients and servers. This ensures that:

      • Only approved users, applications, machines, and endpoints have access to system resources. Consequently, the mechanism can be used by Couchbase SDK clients, to access Couchbase Services; and by source clusters that use XDCR to replicate data to target clusters.

      • Clients can verify the identity of Couchbase Server, thereby ensuring that they are not exchanging data with a rogue entity.

      Full Admin, Local User Security Admin, or External User Security Admin privileges are required, for the management of certificates.

      This page provides a general overview of certificates, and of their management in the context of Couchbase Server. For step-by-step instructions on certificate creation and deployment, see Configure Server Certificates and Configure Client Certificates.

      Certificate Content

      Certificate-based authentication relies on a Certificate Authority (CA), to validate identities and issue certificates. Each certificate includes:

      • The name of the entity it identifies.

      • An expiration date.

      • The name of the CA that issued the certificate.

      • The digital signature either of the issuing CA, or of an intermediate certificate through which the authority of the issuing CA can be traced.

      • A public key, which corresponds to the private key that was used to generate the certificate; and which can therefore potentially be used in conjunction with that private key, so as to handle authentication and secure communication between client and server.

      This information associates the identified entity (that is, the server-node or client bearing the certificate) with the issuing CA, such that third parties who know and trust the CA, but are unfamiliar with the identified entity, may elect to trust the identified entity on the basis of their trust in the CA. Note that all systems that use certificates for authentication maintain their own collection of trusted CA certificates: if, when an entity attempts to authenticate, the entity proves that it has itself been authorized by a CA whose certificate is included in the system’s collection, the entity may be trusted by the system.

      Additionally, certificates can each be configured to contain extensions, which are used to constrain the certificate’s capabilities (for example, by indicating the IP address of the server on which the certificate must reside; or by indicating the uses to which its public key must be restricted); or to identify a username, based on which client-authentication and authorization can proceed.

      Certificate Hierarchies

      On a Couchbase Server-cluster, certificates are managed and deployed hierarchically. The certificate with overall authority for the cluster is at the top of the hierarchy; and its authority is inherited by all certificates on lower tiers of the hierarchy. One certificate issues another certificate — thereby letting the new certificate inherit its own authority and occupy the tier immediately below itself — by the process of certificate signing.

      A two-tier certificate hierarchy is one where the CA certificate has itself issued a certificate directly for one or more identified entities — each of which could be an individual node within a cluster, or a client application that wishes to interact with the cluster. If a third party trusts a CA, then it will also trust an identified entity whose own certificate has been issued by that CA. The CA, being at the top of the two-tier hierarchy, is often referred to as the Root CA.

      A two-plus-tier certificate hierarchy is one where a Root CA has issued a certificate to an intermediate authority, which in turn has issued a certificate either to another intermediate authority, or directly to one or more entities that are to be identified. Use of a two-plus-tier hierarchy requires that all intermediate certificates, as well as a given entity’s certificate, be available for inspection when authentication is attempted; otherwise, the ultimate authority of the root will not be traced, and authentication will fail. All certificates, both on the server-side and on the client-side, should therefore be made available in a complete trust chain: which is a file that contains the entity’s own certificate, concatenated with all its associated intermediate certificates in the order that corresponds to their signing-sequence. The root certificate itself is never included in the trust chain: however, it may be held in an entity’s trust store of trusted certificate-authorities, and recognized on that basis.

      Default Certificates and Certificate Substitution

      By default, Couchbase Server provides minimally defined root and entity certificates to protect cluster and individual nodes. Administrators can replace these, with customized or externally acquired certificates, and with corresponding certificate-chains. All certificates and certificate-chains for client-side use need to be explicitly created and/or deployed by administrators, as appropriate.

      Cluster Certificate

      The cluster certificate is the root certificate issued for the cluster; and contains the public key of the corresponding Certificate Authority (CA). The certificate itself is often referred to as the Root CA. Programs that wish to interact securely with Couchbase Server must elect to trust this CA. By means of certificate signing, the cluster certificate grants its authority to other certificates: this includes both server-side and client-side certificates. Thus, if client and server share the same root certificate, they are likely to trust one another.

      Couchbase Server provides a default, self-signed cluster certificate, which is created and deployed when the first node in a cluster is created. A new, replacement cluster certificate can be deployed on the cluster by means of the Couchbase REST API or CLI. The current cluster certificate is always visible on the Root Certificate panel of the Security screen of Couchbase Web Console. See Root Certificate.

      The file for the cluster certificate (indeed, for any other server or client certificate) is required to be in Privacy Enhanced Mail (or PEM) format, with a .pem extension. The file can have any name, although ca.pem is commonly used. On creation, the certificate is generated (indeed, all certificates, whether server-side or client-side are generated) from a corresponding, already created private key; whose file is in PKCS #1 RSA key format, with a .key extension. The name of the private key often corresponds to the name of the certificate it generates: for example, ca.key would be used to generate ca.pem. When an existing certificate is to be used to grant its authority to another, the existing certificate’s .key and .pem files are both specified in the creation-process for the new certificate.

      Note that the private key of the default, self-signed cluster certificate is not made available. Consequently, custom certificate-chains based on the default certificate cannot be created. To create custom certificate-chains, a custom cluster certificate and private key must be generated (or alternatively, a Root CA must be acquired from an external authority, and certificate-chains then created based on an authority-signed intermediate certificate, as described below).

      Examples of creating cluster and other certificates based on private keys are provided in Configure Server Certificates

      Intermediate Certificates

      An intermediate certificate (sometimes referred to as a subordinate certificate, an Intermediate CA, or a Signing CA) can be either:

      • A certificate signed by the cluster certificate (the Root CA).

      • One of a chain of intermediate certificates, each of which has been signed by that preceding it in the chain; except the first, which has been signed by the cluster certificate.

      The main purpose of the intermediate certificate is to sign node certificates, client certificates, or other intermediate certificates; and thereby convey the authority of the cluster certificate to the node or client certificates indirectly. This allows the cluster certificate’s own private key to be only minimally used (and thereby more securely maintained) when multiple nodes or clients need to be signed — possibly across multiple clusters, subnets, or data centers.

      The default certificates provided by Couchbase Server do not include intermediates: entity certificates are all signed directly by the root (the cluster certificate). However, if customized certificates and certificate-chains are substituted by the administrator, intermediate certificates can be defined and used.

      Node Certificates

      A node certificate, signed directly by the cluster certificate, is assigned to each node in a Couchbase Cluster by default. The process whereby default node certificates are generated (based on a new private key) and signed (by means of the current cluster certificate and cluster private key) is entirely automated; and occurs whenever a single-node cluster is created, and whenever additional nodes are added or joined. Certificate-based security for a Couchbase Server-cluster is thereby provided, in a limited form, out-of-the-box (supporting, for example, all the standard Couchbase-Server secure ports — which are described in Couchbase Server Ports — and Node-to-Node Encryption). However, broader security requirements may need to be supported by means of customized certificates, configured to include special extensions and Subject Alternative Names, based on an administrator-selected root authority.

      When customized node certificates have been prepared for a cluster, the following elements must be deployed on each node of the cluster, for its node certificate to become active:

      • The node private key, which has been used to create the node certificate for the current node. On each node, this must be named pkey.key.

      • The node certificate chain-file. On each node, this must be named chain.pem. When the node certificate has been signed directly by the cluster certificate, chain.pem is nothing more than the node certificate file, renamed. However, when the node certificate has gained the CA’s authority by means of a sequence of one or more intermediate certificates, chain.pem must be a correspondingly ordered concatenation of all the certificates in the chain, except the cluster certificate. Access to this file allows the authority of the node certificate to be established by progressive examination of the signing authorities in its chain.

      Couchbase Server requires that these files, when newly created, be manually copied to a specific location in the filesystem: from this location, they are deployed by Couchbase Server. Examples are provided in Configure Server Certificates.

      Unlike the cluster certificate, the text of which is displayed in Couchbase Web Console (as described in Root Certificate), node certificates (whether defaults or customized substitutions) are not displayed to users; nor are the corresponding chain files.

      Client Certificates

      A Couchbase Server-client can use a client certificate to identify itself to Couchbase Server: this allows the server to authenticate the client, and to authorize the client’s associated user. Information included in the certificate identifies the user by means of a username.

      Couchbase Server creates and uses client certificates by default, for inter-node communication; but these are not visible to the user. Client certificates required for XDCR or SDK-client access must be explicitly created by the administrator; based on a customized, replacement cluster certificate.

      When authenticating a client that uses certificate-based authentication, Couchbase Server asks the client to present the client certificate. Couchbase Server determines whether to trust the client certificate: if the client certificate is determined to have a root authority that is recognized by Couchbase Server, the client certificate may be trusted. The certificate’s time-validity and other details are checked. If the certificate has not expired and is valid in all other necessary respects, the username provided by the certificate is determined, and this is checked by Couchbase Server against registered users and their roles. If the user exists, and the associated roles are appropriate, access is granted; otherwise, access is denied.

      Note that the private key used to create the client certificate is itself used in the process whereby the client authenticates itself against the server: the client digitally signs a message, using its private key, and sends this message to the server; allowing the client’s public key then to be used by the server to verify that the message has indeed been sent by the client. An example of specifying the private key for this purpose, in the context of securing XDCR, is provided in Specify Root and Client Certificates, and Client Private Key. A further example, in the context of securing contact with an LDAP host, is provided in Configure LDAP.

      Note also that these steps, whereby the client authenticates with the server, are additionally followed to allow the server to authenticate with the client. The overall, two-way authentication process is referred to as mutual TLS (mTLS) or mutual authentication.

      Specifying Usernames for Client-Certificate Authentication

      The username to be authorized by Couchbase Server can be specified by means of several elements included in the client certificate. Couchbase Server can be configured to search for appropriate elements within the client certificate; and then attempt to authenticate and authorize, using each element as the basis for a Couchbase-Server username.

      If multiple elements within the client certificate are so used, the first to be successfully authenticated by Couchbase Server is the one used. The order in which the elements are examined is that configured on Couchbase Server, as described in Enable Client Certificate Handling.

      Embedding Usernames in Certificates

      Within a certificate presented for authentication, the elements that can be used to specify a username include the following:

      • The Subject for the certificate, featuring the Common Name. For example, on the command-line, during client-certificate preparation, -subj "/CN=clientuser" might be specified; to allow clientuser to be identified as the username.

        Note that use of Subject Common Name is now deprecated (see section 6.4.4 of RFC 6125); but continues to be supported by Couchbase Server. See also Deprecation of Subject Common Name, below.

      • The DNS name, provided as a Subject Alternative Name for the certificate. For example, subjectAltName = DNS:node2.cb.com would, with no prefix or delimiter specified in the Couchbase Server handling-configuration, allow node2.cb.com to be identified as the username.

        Prefix and delimiter are explained below, in Identifying Certificate-Based Usernames on Couchbase Server.

      • The email, provided as a Subject Alternative Name for the certificate. For example, subjectAltName = email:john.smith@mail.com would, with no prefix configured or delimiter specified, allow john.smith@mail.com to be extracted and identified as the username. Note, however, that since the character @ is not permitted in Couchbase Server usernames, no such user could exist. Nevertheless, the user john.smith could be defined on Couchbase Server; and this name could be extracted from john.smith@mail.com, given appropriate server-side configuration of a delimiter, as explained in Identifying Certificate-Based Usernames on Couchbase Server, below.

      • The URI provided as a Subject Alternative Name for the certificate. For example, subjectAltName = URI:www.acme.com would, with no prefix or delimiter specified, allow www.acme.com to be extracted and identified as the username.

      Examples of specifying Subject Common Names and Subject Alternative Names are provided in Configure Server Certificates and Configure Client Certificates.

      Identifying Certificate-Based Usernames on Couchbase Server

      Client-certificate handling is disabled by default on Couchbase Server: it can optionally be enabled; and if required, specified as mandatory.

      When client-certificate handling has been enabled, paths specified within the client certificate can be configured to be searched for, in order to retrieve usernames for authentication.

      Each specified path can be one of the following path-types:

      • subject.cn. The Subject Common Name specified in the certificate will be extracted.

      • san.dns. The DNS Subject Alternative Name for the certificate will be extracted.

      • san.email. The email Subject Alternative Name for the certificate will be extracted.

      • san.uri. The URI Subject Alternative Name for the certificate will be extracted.

      Any number of paths can be specified on Couchbase Server, with multiple instances of any path-type.

      The name retrieved by searching for a Couchbase Server-specified path can optionally be parsed, so that the symbols that constitute the username are isolated from extraneous characters. This is achieved by associating the path with a specified prefix and/or delimiter:

      • If neither a prefix nor a delimiter is specified for a given path, no parsing of the corresponding name is attempted; and authentication is attempted with the unparsed name.

      • If only a prefix is specified for a given path, parsing is attempted in accordance with the specified prefix. If no instance of the prefix is located in the name, authentication is then attempted with the name unchanged.

      • If only a delimiter is specified for a given path, parsing is attempted in accordance with the specified delimiter. If no instance of the delimiter is located in the name, authentication is then attempted with the name unchanged.

      • If both a prefix and a delimiter are specified for a given path, parsing is attempted for each in turn — prefix first, then delimiter — as described above. Authentication is then attempted with the string produced by these sequential parsing-attempts.

      Prefix and delimiter are defined as follows:

      • Prefix: One or more characters that, if exactly matched with the substring that begins the string specified as the Subject Common Name or Subject Alternative Name, are removed from that string. For example, if a certificate-specified san.uri is www.couchbase.com, and the server-specified prefix is www., then www. is removed from www.couchbase.com, leaving the string couchbase.com.

        However, if a certificate-specified san.uri is foo.bar.com, and the server-specified prefix is www., nothing is removed from foo.bar.com.

      • Delimiter: A single character that, if matched with a single instance in the string being parsed, causes both itself and all subsequent characters to be discarded from the string. For example, a delimiter of . causes the substring .com to be discarded from couchbase.com; and leaves couchbase as the username to be authenticated.

        Note that if a string contains multiple instances of the character specified as the delimiter, the first instance is the one used. For example, a delimiter of . causes the substring .couchbase.com to be discarded from www.couchbase.com, leaving www as the username to be authenticated.

      For step-by-step instructions, see Enable Client Certificate Handling.

      Deprecation of Subject Common Name

      Use of the Subject Common Name to identify either a server or a client is now deprecated (see section 6.4.4 of RFC 6125). For Couchbase Server, this means that:

      • The node-certificate for each server in the cluster is recommended to specify at least one Subject Alternative Name, in order to be identified: typically, the node’s IP address or DNS name should be provided in this way. Subject Common Name may continue to be specified.

      • A client-certificate may continue to specify only a Subject Common Name.

      Examples of certificate-creation provided in Manage Certificates continue to include definitions of Subject Common Name for both server and client.

      Examples

      Examples of file-types and their generation, of extension-definition, of intermediate-certificate use, and of Couchbase-Server specific deployment requirements are provided for the server-side in Configure Server Certificates, and for the client-side in Configure Client Certificates. The examples allow Cross Data Center Replication to be secured with certificates only. They also support secure access to Couchbase Server from Java clients.