Configure Server Certificates
Couchbase Server Enterprise Edition supports X.509 certificates, for the encryption of communications between the server and networked clients.
Configure Server Certificates
This section demonstrates how server certificates can be configured for Couchbase Server. Note that the procedures are provided only as limited examples, giving guidance as to the basic steps typically involved in certificate creation. Modification of the procedures will likely be required, for the preparation of certificates for different platforms and cluster-configurations.
Two procedures are provided, each of which configures X.509 certificates on Ubuntu 16 for a one-node Couchbase Server-cluster. Before attempting to follow either procedure, see the conceptual and architectural information provided in Certificates.
The first procedure, Cluster Protection with Root and Node Certificates, is the simpler: it shows how to create a root certificate that is a trusted, self-signed authority; and how to use this to sign individual, per node certificates. The second procedure, Cluster Protection with Root, Intermediate, and Node Certificates, demonstrates how a created root certificate is used to sign one or more intermediate certificates; which are then in turn used to sign individual, per node certificates: such use of intermediate certificates allows the root certificate itself to be kept private when node-certificate or client-certificate signing is required.
Cluster Protection with Root and Node Certificates
The following procedure shows how to create a root certificate that is the trusted, self-signed authority used to sign individual, per node certificates. Note that corresponding, subsequent procedures that create certificates for client-authentication are provided in Client Access: Root Certificate Authorization and Java Client Access: Root Certificate Authorization.
Proceed as follows:
-
On the server to be certificate-protected, create working directories:
mkdir servercertfiles cd servercertfiles mkdir -p {public,private,requests}
The
public
directory will be used to store certificates, which contain public keys. Theprivate
directory will contain private keys. Therequests
directory will store certificate signing requests, which are files generated from private keys: when a signing request is granted the signature of an appropriate authority, a signed certificate is produced. -
Create a private key for the cluster.
A private key can be used to decrypt data previously encrypted by the corresponding public key. It can also be used to encrypt a digital signature, to be decrypted by the public key. In the key-creation sequence, the private key is created first. Then, the public key is created, being derived from the private key.
Enter the following:
openssl genrsa -out ca.key 2048
The output of this command,
ca.key
, is the private key for the cluster. -
Create the certificate (that is, the file that will contain the public key) for the cluster. The certificate is intended to be self-signed, meaning that it will not be vouched for by any other authority. This means that it can be created directly, based on the existing private key
ca.key
, without assistance from a third party.Enter the following:
openssl req -new -x509 -days 3650 -sha256 -key ca.key -out ca.pem \ -subj "/CN=Couchbase Root CA"
The
x509
flag indicates that in this case, an x509 structure, rather than a request is to be generated. (By contrast, a request will need to be generated whenever the signature of a third-party authority is required: this is demonstrated below.) Thedays
flag specifies the number of days for which the certificate should be active. The hashing algorithm to be used for digital-signature creation is specified assha256
. The private key file on which the certificate is to be based is specified asca.key
, and the output-certificate is named asca.pem
. The certificate’s issuer is specified to have theCN
(Common Name) ofCouchbase Root CA
: as this name indicates, the certificate will be the root certificate for the Couchbase Server-cluster.The output of the command is the certificate
ca.pem
; which contains the public key corresponding to the cluster’s private key,ca.key
.Optionally, the public key within the certificate can be displayed as follows:
openssl x509 -in ./ca.pem -noout -pubkey
The output has approximately the following appearance:
-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3HMfiSjCwakfMbA20HUd V372JbQG9UGjf9V3xyMa90IHFD8cFjPYao7SZOpe0nkm2UmZRgQbTwWxC4CZqrYZ pyrWLn9rjDFkzzbRjMRcZv2D0s0KkPrNYxfHj3cL/j5bpB4/hquvb4RglMkyyJo9 mVx19lF4mtEsBqPGZBGArbzeArn4c1e6I4mqIfb9Vne/7vhIzLLSXoT5FmifWyGQ 4B9BSIrE9Ildwhez699MGfj+N+0xg2wTOIUVNvS1c5gF/uDS6t9Aswb60W+hjtF4 d1ZBKBIVkmPGX0XOgGtdndXza4sjVkh3bB/ipWo9zUJYwFCWkofbqGeSnSz9n9o6 fwIDAQAB -----END PUBLIC KEY-----
Note that by substituting other flags for
-pubkey
, other characteristics of the certificate can be displayed.-issuer
displays the certificate’s issuer, and-subject
its subject (in both cases,subject= /CN=Couchbase Root CA
). The-version
,-serial
,-subject-hash
, and more can be displayed.The entire certificate can be displayed as text, by means of the following command:
openssl x509 -text -noout -in ./ca.pem
The initial part of the output, which is extensive, is as follows:
Certificate: Data: Version: 3 (0x2) Serial Number: 18276610881715621025 (0xfda390c366b2cca1) Signature Algorithm: sha256WithRSAEncryption Issuer: CN=Couchbase Root CA Validity Not Before: Sep 2 08:32:31 2019 GMT Not After : Aug 30 08:32:31 2029 GMT Subject: CN=Couchbase Root CA Subject Public Key Info: Public Key Algorithm: rsaEncryption Public-Key: (2048 bit) Modulus: 00:d7:a6:ba:5d:e2:e2:fd:6e:1b:33:9a:4b:bf:77: 6f:28:c3:37:60:33:da:09:b2:0b:73:1f:f9:65:2a: . .
The displayed text thus provides information including the
Version
, theSerial Number
, and theSignature Algorithm
of the certificate. The certificate’sIssuer
,Subject
, and period ofValidity
are also shown. TheAlgorithm
andModulus
(and, further below, theExponent
) of the public key are shown.For detailed information on keys and key-generation, see RSA (cryptosystem).
-
Create a private key for the individual node.
In addition to the root certificate and private key for the entire cluster, which are
ca.pem
andca.key
, a node certificate and private key must also be created. The node certificate, along with its corresponding node-private key, will reside on its own, corresponding node. When deployed, each node certificate must be namedchain.pem
, and each node private keypkey.key
. Consequently, if the node certificates and private keys for multiple nodes are being prepared on a single system, the files should be given individual, distinctive names on creation; and then each deployed on its appropriate node as eitherchain.pem
orpkey.key
. This renaming procedure is indeed followed here for demonstration purposes, even though only a one-node cluster is involved.Create the node private key as follows:
openssl genrsa -out private/couchbase.default.svc.key 2048
The output file is
couchbase.default.svc.key
, which is the private key for the node. -
Create a certificate signing request for the node certificate. This step allows the materials required for certificate-creation to be passed to a third-party, who will digitally sign the certificate as part of its creation-process, and thereby confirm its validity. (In this demonstration, however, no actual third-party is involved: the certificate will be signed by means of the root private key, which is owned by the current user.)
Enter the following command:
openssl req -new -key private/couchbase.default.svc.key \ -out requests/couchbase.default.svc.csr -subj "/CN=Couchbase Server"
The
key
specified as the input for the request iscouchbase.default.svc.key
, which was created in the last step. The output request-file is specified ascouchbase.default.svc.csr
. Note that this can be inspected as text, by entering the following command:openssl req -text -noout -verify -in ./requests/couchbase.default.svc.csr
The initial part of the displayed output, which is extensive, is as follows:
verify OK Certificate Request: Data: Version: 0 (0x0) Subject: CN=Couchbase Server Subject Public Key Info: Public Key Algorithm: rsaEncryption Public-Key: (2048 bit) Modulus: 00:be:26:e5:06:c6:8e:43:bb:9d:bc:84:20:34:8e: db:2f:d1:8b:b4:ff:c2:66:c0:61:70:8d:c3:8c:df: . .
The
Version
andSubject
of the request are listed, along with information on the public key that is to be included in the certificate. -
Define certificate extensions for the node.
Certificate extensions specify constraints on how a certificate is to be used. Extensions are submitted to the signing authority, along with the certificate signing request.
For example, the certificate’s public key can be specified, by means of the
keyUsage
extension, to support digital signatures, but not to support key encipherment — or, the opposite can be specified; or, support of both digital signatures and key encipherment can be specified. Meanwhile, thesubjectAltName
extension can be used to specify the DNS name and IP address of the server on which the certificate resides; so that if the certificate is deployed in any other context, it becomes invalid.For detailed information on certificate extensions, see the Standard Extensions section of the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL Profile).
Certificate extensions can be defined in a file, whose pathname is then provided as a parameter to the
openssl
command used to create the certificate. Thus, such server-certificate extensions as are intended to be generic across all cluster-nodes might be written as follows:cat > server.ext <<EOF basicConstraints=CA:FALSE subjectKeyIdentifier = hash authorityKeyIdentifier = keyid,issuer:always extendedKeyUsage=serverAuth keyUsage = digitalSignature,keyEncipherment EOF
The value of
extendedKeyUsage
is specified asserverAuth
, indicating that the cluster is to be used for server authentication. The values ofkeyUsage
aredigitalSignature
, specifying that the certificate’s public key can be used in the verifying of information-origin; andkeyEncipherment
, specifying that the public key can be used in the encrypting of symmetric keys (through the exchange and use of which symmetrically encrypted communications between server and client can occur). -
Create a customized certificate extensions file, which adds per node constraints to the generic constraints already specified.
cp ./server.ext ./server.ext.tmp echo "subjectAltName = DNS:node2.cb.com,IP:10.143.192.102" \ >> ./server.ext.tmp
This customized extensions file is to be used to authenticate a single node, whose DNS name of the server-node is
node2.cb.com
, and its IP address is10.143.192.102
. If experimentation is being performed locally, the/etc/hosts
file for the local machine should contain a line such as the following:10.143.192.102 node2.cb.com
The creation of the customized extensions file should occur once for each node, with each customized extensions file containing only those extensions that apply to the current node.
-
Create the node certificate, applying the certificate and digital signature of the appropriate authority, and the customized extensions file for the node, to the materials in the signing request.
Enter the following:
openssl x509 -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 -req \ -in requests/couchbase.default.svc.csr \ -out public/couchbase.default.svc.pem \ -extfile server.ext.tmp
The file generated by this command,
couchbase.default.svc.pem
, is the node certificate. The root certificate and private key,ca.pem
andca.key
, are specified as input values to the certificate-creation command. This ensures that the new certificate’s chain of trust includes the root certificate,ca.pem
, and is digitally signed byca.key
; allowing that signature to be verified as required, through decipherment by means of the public key embedded inca.pem
.The following confirmatory output is displayed:
Signature ok subject=/CN=Couchbase Server Getting CA Private Key
Note that if a node certificate were actually submitted to an external authority for signing, then the authority’s own
pem
andkey
would be specified as inputs, rather thanca.pem
andca.key
: and in such a case, the authority’spem
would need to become the root certificate for the cluster. -
Rename the node certificate and node private key.
For deployment on the node, the node certificate must be renamed
chain.pem
; and the node private key renamedpkey.key
. Proceed as follows:cd ./public mv couchbase.default.svc.pem chain.pem cd ../private mv couchbase.default.svc.key pkey.key
-
Deploy the node certificate and node private key.
These are deployed by being moved to the
inbox
directory of the server, and made executable. Proceed as follows:cd .. sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/ sudo cp ./public/chain.pem /opt/couchbase/var/lib/couchbase/inbox/chain.pem sudo cp ./private/pkey.key /opt/couchbase/var/lib/couchbase/inbox/pkey.key
-
Upload and activate the root certificate for the cluster.
The root certificate is uploaded and activated with the following REST commands:
curl -X POST --data-binary "@./ca.pem" \ http://Administrator:password@10.143.192.102:8091/controller/uploadClusterCA curl -X POST \ http://Administrator:password@10.143.192.102:8091/node/controller/reloadCertificate
The root certificate is now deployed and ready for use. This can be verified by means of Couchbase Web Console. Access the Security screen, by means of the Security tab in the left-hand navigation bar. Then, left-click on the Root Certificate tab, located on the upper, horizontal navigation bar.
The screen appears as follows:
As this indicates, the signed certificate has now been substituted for the default certificate (an example of whose appearance is provided in Root Certificate).
Note that authentication by means of a client certificate must be specifically enabled: see Client Certificate Enablement, below.
Configuring Client Access
Once the cluster has been protected by the deployment of root and node certificates described above, a client certificate can be signed by the root certificate, to allow a client to access the cluster. Client-certificate preparation varies, depending on the type of client to be supported. For steps to prepare a certificate supportive of Couchbase Server, see Client Access: Root-Certificate Authorization. For steps to prepare a certificate supportive of a Java client, see Java Client Access: Root-Certificate Authorization.
Note that access by means of a client certificate must be specifically enabled, on the cluster that is to be accessed: see Client Certificate Enablement, below.
Cluster Protection with Root, Intermediate, and Node Certificates
Optionally, a root certificate can be used to sign an intermediate certificate, which is then itself used to sign node certificates. This allows the root certificate to be kept private, when node-certificate or client-certificate signing is required.
The steps and descriptions below assume that the previous procedure, Cluster Protection with Root and Node Certificates, has already been successfully completed; and that familiarity with the basic certificate-related concepts explained there has been attained.
Note that corresponding, subsequent procedures that create certificates for client-authentication are provided in Client Access: Intermediate Certificate Authorization and Java Client Access: Intermediate Certificate Authorization
Proceed as follows:
-
On the server to be certificate-protected, create working directories:
mkdir servercertfiles2 cd servercertfiles2 mkdir -p {root,servers,clients}/{issued,reqs,private}
The directories
root
,servers
, andclients
will contain the issued certificates, requests, and private keys generated for the root, the individual nodes, and clients wishing to access the nodes. Each directory therefore containsissued
,reqs
, andprivate
subdirectories.Note that this directory infrastructure will also be used in the subsequent process, Client Access: Intermediate Certificate Authorization; where the contents of the
clients
directory will be created. -
Change directory to
root
. Then, create a configuration file for the root certificate that is to be created.cd root cat > config <<EOF [req] distinguished_name = cn_only x509_extensions = ca_ext [ cn_only ] commonName = Common Name (eg: your user, host, or server name) commonName_max = 64 commonName_default = CA [ca_ext] basicConstraints = CA:TRUE subjectKeyIdentifier = hash authorityKeyIdentifier = keyid:always,issuer:always keyUsage = cRLSign, keyCertSign EOF
The
config
file has three sections. The first,req
, specifies values to be passed to thereq
command, which is used to create and process certificate requests: useman req
to obtain information on the values passed. The second section,cn_only
, provides specifications for the Common Name to be used in the certificate, including the maximum number of characters and the default name. The third section,ca_ext
, provides basic extensions that limit the capability of the certificate. These include a value ofTRUE
forCA
, indicating that the certificate will be able to provide signing authority for other certificates. Addtionally, the values forkeyUsage
are provided ascRLSign
, indicating that the certificate’s public key will be usable to verify signatures on Certificate Revocation Lists; andkeyCertSign
, indicating that the certificate’s public key will be usable to verify signatures on other certificates. -
Create the root certificate, specifying the created
config
file.openssl req -config config -new -x509 -days 3650 -sha256 -newkey rsa:2048 \ -keyout ca.key -out ca.pem -subj '/C=UA/O=MyCompany/CN=RootCA'
This specifies that both the root certificate for the cluster and its private key be created. The key is additionally specified to be encrypted. In consequence, during execution, the following prompt is displayed:
Generating a 2048 bit RSA private key ....+++ ...................+++ writing new private key to 'ca.key' Enter PEM pass phrase:
This requires that a pass phrase be entered, for inclusion of the key in command-line procedures, such as those used for certificate generation. The phrase will be stored in the certificate, and prompted for whenever administrative access is attempted. Enter an appropriate phrase: a second prompt then appears, requesting confirmation of the phrase. Enter the phrase again, and the operation completes.
The output file,
ca.pem
is the root certificate for the cluster, and is saved in theroot
folder. (Note that in the steps that follow, other certificates namedca.pem
are created in additional folders: these should not be confused with the certificate of the same name inroot
.) -
Create an extensions file that will limit the capabilities of the intermediate certificate that is to be created.
Enter the following:
cat > ca.ext <<EOF basicConstraints = CA:TRUE subjectKeyIdentifier = hash authorityKeyIdentifier = keyid:always,issuer:always keyUsage = cRLSign, keyCertSign EOF
Here,
CA
is set toTRUE
, meaning that the intermediate certificate will be able to act as an authority for other certificates (specifically, for the individual, per node certificates used by the cluster). The specifiedkeyUsage
includes the valuekeyCertSign
, meaning that the intermediate certificate’s public key will be used to verify signatures that appear on other certificates. -
Create a private key and corresponding certificate signing request for the intermediate certificate.
openssl req -new -sha256 -newkey rsa:2048 -keyout ../servers/ca.key \ -out reqs/server-signing.csr \ -subj '/C=UA/O=MyCompany/OU=Servers/CN=ServerSigningCA'
Again, the key is specified to be encrypted. Therefore, prompts appear, asking for a pass phrase for the certificate. Enter an appropriate phrase in response to the prompts.
The output from the request consists of the encrypted private key
../servers/ca.key
and the signing-requestserver-signing.csr
. -
Create the intermediate certificate, specifying the root certificate
ca.pem
and its keyca.key
, to establish the root certificate’s authority.openssl x509 -CA ca.pem -CAkey ca.key -CAcreateserial \ -CAserial serial.srl -days 3650 -req -in reqs/server-signing.csr \ -out issued/server-signing.pem -extfile ca.ext
Since this specifies that the encrypted key
ca.key
be used to sign the intermediate certificate, the user is prompted for the appropriate pass phrase. Enter the phrase against the prompt.The extension file
ca.ext
is thus applied to the certificate, so as to limit the certificate’s capabilities. The certificate is generated and saved in thereqs
folder asserver-signing.pem
. -
Save the intermediate certificate as the authority for the node certificates that are to be created.
cp issued/server-signing.pem ../servers/ca.pem
-
Within the
../servers
directory, create an extension file containing the information that will be generic across all the individual nodes of the cluster.cd ../servers cat > server.ext <<EOF basicConstraints = CA:FALSE subjectKeyIdentifier = hash authorityKeyIdentifier = keyid,issuer:always extendedKeyUsage = serverAuth keyUsage = digitalSignature,keyEncipherment EOF
The
extendedKeyUsage
valueserverAuth
indicates that the certificate will be used for server authentication. ThekeyUsage
valuedigitalSignature
specifies that the certificate’s public key can be used in the verifying of information-origin; whilekeyEncipherment
allows the public key to be used in the encrypting of symmetric keys. -
Generate the private key to be used for each individual cluster-node.
openssl genrsa -out private/couchbase.node.svc.key 2048
The private key
couchbase.node.svc.key
is thus saved in theprivate
folder, as the private key for each node in the cluster. -
Generate the certificate signing request for the node certificate.
openssl req -new -key private/couchbase.node.svc.key \ -out reqs/couchbase.node.svc.csr \ -subj "/C=UA/O=MyCompany/OU=Servers/CN=couchbase.node.svc"
The signing-request file
couchbase.node.svc.csr
is thus saved in thereqs
folder. -
Add node-specific information for each node, in turn. Although the current example features a single-node cluster, this step would be repeated for each node in the cluster, if the cluster contained multiple nodes: in each case, the node-specific information (here, DNS name and IP address) being different.
cp server.ext temp.ext echo 'subjectAltName = DNS:node2.cb.com,IP:10.143.192.102' >> temp.ext
This creates
temp.ext
as an extension file that will be used for one node only. The file specifies the DNS name and IP address specific to the node. -
Create the node certificate for an individual node, specifying the unique extension file for the node, and specifying the intermediate certificate and key as the signing authority.
openssl x509 -CA ca.pem -CAkey ca.key -CAcreateserial \ -CAserial serial.srl -days 365 -req -in reqs/couchbase.node.svc.csr \ -out issued/couchbase.node.svc.pem -extfile temp.ext
Since this specifies that the certificate should be signed by the encrypted intermediate key,
ca.key
, a prompt appears, requesting the appropriate pass phrase. Enter the phrase against the prompt.The node-certificate file
couchbase.node.svc.pem
is hereby saved in theissued
folder. The certificate bears the constraints specified intemp.ext
, and is granted the authority of the intermediate certificate and key, which areca.pem
andca.key
respectively. -
Check that the node certificate is valid. The following use of the
openssl
command verifies the relationship between the root certificate, the intermediate certificate, and the node certificate.openssl verify -trusted ../root/ca.pem -untrusted ca.pem \ issued/couchbase.node.svc.pem
If the certificate is valid, the following output is displayed:
issued/couchbase.node.svc.pem: OK
-
Prepare to deploy the certificate and private key for the node. First, concatenate the node certificate and the intermediate certificate, to establish the chain of authority. Then, rename the private key for the node.
cat issued/couchbase.node.svc.pem ca.pem > chain.pem cp private/couchbase.node.svc.key pkey.key
This step, and each of the following steps in this procedure, must be performed for each node in the cluster.
-
Move the node certificate and node private key into the
inbox
for the current node.sudo mkdir /opt/couchbase/var/lib/couchbase/inbox/ # if needed sudo cp ./chain.pem /opt/couchbase/var/lib/couchbase/inbox/chain.pem sudo cp ./pkey.key /opt/couchbase/var/lib/couchbase/inbox/pkey.key
-
Upload and activate the root certificate.
cd ../root curl -X POST --data-binary "@./ca.pem" \ http://Administrator:password@10.143.192.102:8091/controller/uploadClusterCA curl -X POST http://Administrator:password@10.143.192.102:8091/node/controller/reloadCertificate
This concludes the certificate-deployment process. The root certificate can be examined by means of Couchbase Web Console, as shown in Step 10 of the previous example on this page.
Configuring Client Access
Once the cluster has been protected by the deployment of root, intermediate, and node certificates described above, a client certificate can be signed by a client-intermediate certificate that itself inherits the authority of the root: this allows the client certificate to access the cluster. Client-certificate preparation varies, depending on the type of client to be supported. For steps to prepare a certificate supportive of Couchbase Server, see Client Access: Intermediate-Certificate Authorization. For steps to prepare a certificate supportive of a Java client, see Java Client Access: Intermediate-Certificate Authorization.
Note that access by means of a client certificate must be specifically enabled, on the cluster that is to be accessed: see Client Certificate Enablement, below.
Client-Certificate Enablement
As well as using its own certificates to authenticate with clients, Couchbase Server may also allow clients' use of their own certificates; whereby they authenticate themselves with Couchbase Server. The handling of client certificates by the server must be explicitly enabled. For information on enablement options and identity encodings, see Client Certificates. For an introduction to the user interface provided by Couchbase Web Console, see Client Certificate. For information on performing enablement with Couchbase Web Console, the CLI, and the REST API, see Enable Client-Certificate Handling.
The REST API might be used to enable client-certificate handling as follows:
curl -u Administrator:password -v -X POST \ http://10.143.192.102:8091/settings/clientCertAuth \ -d '{"state": "enable","prefixes": [{"path": \ "subject.cn","prefix": "","delimiter": ""}]}'
Further Information
For further information on certificate-deployment, see ssl-manage and Encryption On-the-Wire API.
For step-by-step instructions on creating client certificates, see Configure Client Certificates.
For an example of using the certificates and keys created on the current page and on Configure Client Certificates to secure an XDCR replication, see Specify Root and Client Certificates, and Client Private Key.