Configure Client Certificates
Couchbase Server supports client-authentication by means of X.509 certificates.
Couchbase Client Authentication
Couchbase clients can authenticate by means of X.509 certificates. This page provides step-by-step instructions for the creation of client certificates for:
-
Couchbase Server. The certificate can be used by a Couchbase Server-cluster that wishes to secure its connection to another Couchbase Server-cluster. This certificate might be used by a source cluster that wishes to perform Cross Data Center Replication securely, to a destination cluster.
-
Java Applications. A Java application based on the Couchbase SDK can obtain its client certificate from a Java keystore, and so authenticate with Couchbase Server securely.
For a list of Couchbase-Server ports that provide secure connectivity to clients, see Connectivity.
Configure Client Certificates for Couchbase Server
The section contains two procedures for the creation of a client certificate and key, whereby authentication with Couchbase Server can be performed:
-
Client Access: Root-Certificate Authorization shows how to create a client certificate that is authorized by a cluster’s root certificate. The procedure for creating the cluster’s root certificate (and, based on the root certificate, the cluster’s individual per node certificates), is provided in Cluster Protection with Root and Node Certificates. The instructions on the current page assume that that procedure has already been followed: therefore, they duly make use of the previously created directory structure and files.
-
Client Access: Intermediate-Certificate Authorization shows how to create a client certificate that is authorized by an intermediate certificate; which derives its own authority from the cluster’s root certificate; and which is used instead of the root for the signing of the client certificate. The procedure for creating the cluster’s root, server-intermediate and per node certificates is provided in Cluster Protection with Root, Intermediate, and Node Certificates. The instructions on the current page assume that that procedure has already been followed: therefore, they duly make use of the previously created directory structure and files.
Both procedures additionally assume that the instance of Couchbase Server to be accessed by the client:
-
Contains the sample bucket
travel-sample
: this is the bucket whose contents the client wishes to read and write. For information on sample buckets and how to install them, see Sample Buckets. -
Has a defined, locally authenticated user named
clientuser
, who has been assigned a role that permits reading and writing to thetravel-sample
bucket. For information on creating users and roles, see Manage Users and Roles.
Note that additional information on file-types can be found in the procedures for server-certificate generation; in Configure Server Certificates.
Client Access: Root-Certificate Authorization
Proceed as follows:
-
Within the top-level directory created in Cluster Protection with Root and Node Certificates, create and access a new working directory.
cd servercertfiles mkdir clientcertfiles cd clientcertfiles
-
Create an extensions file for the use of all clients.
cat > client.ext <<EOF basicConstraints = CA:FALSE subjectKeyIdentifier = hash authorityKeyIdentifier = keyid,issuer:always extendedKeyUsage = clientAuth keyUsage = digitalSignature EOF
This specifies a value of
FALSE
forCA
, indicating that the client certificate will not have the ability to act as an authority for other certificates. ItsextendedKeyUsage
is specified asclientAuth
, indicating that the certificate will be used for authenticating a client. ItkeyUsage
is specified asdigitalSignature
, indicating that its public key is usable for data-origin authentication.This extensions file thus contains definitions judged appropriate for all clients. Further constraints can be added for individual clients, as necessary.
-
Create a client private key.
openssl genrsa -out ./travel-sample.key 2048
This creates the private key
travel-sample.key
, and saves it in theclient
directory. -
Generate the client-certificate signing-request.
openssl req -new -key ./travel-sample.key -out ./travel-sample.csr -subj "/CN=clientuser"
The client’s private key,
travel-sample.key
is provided as input for the signing request. The Common Name provided asSubject
for the certificate is specified asclientuser
, which is the name of the server-defined user to be authenticated by the client. The output request-file,travel-sample.csr
, is saved in theclient
directory. -
Customize a client extensions file, with constraints specific to a particular client.
The following addition allows a client to be restricted to authenticating with a server that has the stated DNS and IP identifiers.
cp ./client.ext ./client.ext.tmp echo "subjectAltName = DNS:node2.cb.com,IP:10.143.192.102" \ >> ./client.ext.tmp
-
Create the client certificate, specifying extensions by means of the customized extensions file.
openssl x509 -CA ../ca.pem -CAkey ../ca.key \ -CAcreateserial -days 365 -req -in ./travel-sample.csr \ -out ./travel-sample.pem -extfile ./client.ext.tmp
The root certificate for the cluster, and its corresponding private key,
ca.pem
andca.key
are specified as inputs for certificate generation, so establishing the root certificate’s authority, within the client certificate.The
client.ext.tmp
is specified as the value of theextfile
flag. The output file,travel-sample.pem
, is the client certificate, and is saved inclientcertfiles
.The confirmatory output is as follows:
Signature ok subject=/CN=clientuser Getting CA Private Key
This concludes the process. The client can now use
travel-sample.pem
to authenticate itself as having the authority ofca.pem
(which is shared by the server it intends to access); and provides the username ofclientuser
(which the server associates with a role appropriate for access to thetravel-sample
bucket). The client key,travel-sample.key
, can be used for digital signing.A possible use case for the client certificate thus generated is described below, in Using Client and Server Certificates for Secure XDCR.
Client Access: Intermediate-Certificate Authorization
The following procedure demonstrates how an intermediate certificate, with the authority of the root certificate, can be created in order itself to sign client certificates. The procedure assumes that the server-equivalent procedure described in Cluster Protection with Root, Intermediate, and Node Certificates has already been followed; and that the resulting directory-structure is still available.
Proceed as follows:
-
Access the
servercertfiles2/root
directory, created in Cluster Protection with Root, Intermediate, and Node Certificates.cd servercertfiles2/root
-
Create an encrypted private key and a certificate signing request, for an intermediate certificate that is to be used for signing client certificates.
openssl req -new -sha256 -newkey rsa:2048 -keyout ../clients/ca.key \ -out reqs/client-signing.csr \ -subj '/C=UA/O=MyCompany/OU=People/CN=ClientSigningCA'
Since this specifies that an encrypted private key be created, prompts appear requesting entry of an appropriate pass phrase. Enter an appropriate phrase against the prompts.
This new private key is named
../clients/ca.key
. The signing-request file is saved asreqs/client-signing.csr
. -
Create the intermediate certificate to be used for client-certificate signing.
openssl x509 -CA ca.pem -CAkey ca.key -CAcreateserial -CAserial serial.srl \ -days 3650 -req -in reqs/client-signing.csr -out issued/client-signing.pem \ -extfile ca.ext
The root certificate and key for the cluster,
ca.pem
andca.key
, are specified as the authority for the intermediate certificate. Sinceca.key
is an encrypted key, a prompt appears, requesting that the appropriate pass phrase be entered: enter the appropriate phrase.Note that the extension file used here to constrain the capabilities of the intermediate certificate is that created in Cluster Protection with Root, Intermediate, and Node Certificates.
-
Save the intermediate certificate as the certificate-authority for the client certificate that is to be created.
cp issued/client-signing.pem ../clients/ca.pem
-
Within the
../clients
directory, create an extension file for the client certificate:cd ../clients cat > client.ext <<EOF basicConstraints = CA:FALSE subjectKeyIdentifier = hash authorityKeyIdentifier = keyid,issuer:always extendedKeyUsage = clientAuth keyUsage = digitalSignature EOF
The value of
extendedKeyUsage
is specified asclientAuth
, indicating that the certificate will be used to authenticate a client. The value ofkeyUsage
is specified asdigitalSignature
, indicating that the certificate may be used in the verifying of information-origin. -
Create a private key for the client certificate.
openssl genrsa -out private/clientuser.key 2048
-
Create a certificate signing request for the client certificate.
openssl req -new -key private/clientuser.key -out reqs/clientuser.csr \ -subj "/C=UA/O=MyCompany/OU=People/CN=clientuser"
The signing request is based on the private key
clientuser.key
. The username associated with the certificate is specified asclientuser
: this is the username to be recognized by Couchbase Server, and associated with specific roles. -
Create the client certificate.
openssl x509 -CA ca.pem -CAkey ca.key -CAcreateserial -CAserial serial.srl \ -days 365 -req -in reqs/clientuser.csr \ -out issued/clientuser.pem -extfile client.ext
This creates the client certificate
clientuser.pem
, based on the signing requestclientuser.csr
, and signed with the authority of the intermediate certificate and key,ca.pem
andca.key
. Sinceca.key
is encrypted, a prompt appears, requesting entry of the appropriate pass phrase: enter the appropriate phrase against the prompt. The certificate is saved in theissued
folder. -
Check the validity of the client certificate. The following use of the
openssl
command verifies the relationship between the root certificate, the client-intermediate certificate, and the client certificate.openssl verify -trusted ../root/ca.pem -untrusted ca.pem \ issued/clientuser.pem
If the certificate is valid, the following output is displayed:
issued/clientuser.pem: OK
-
Concatenate the issued client certificate with the client-intermediate certificate, to establish the chain of authority.
cat issued/clientuser.pem ca.pem > clientuser.pem
The result of the concatenation,
clientuser.pem
is the completed client certificate.
Using Client and Server Certificates for Secure XDCR
Examples of using the certificates and keys created on this page above and in Configure Server Certificates can be found in the documentation provided for securing Cross Data Center Replication, in Specify Root and Client Certificates, and Client Private Key. When securing XDCR according to these instructions, use the following files:
-
If the procedures explained in Cluster Protection with Root and Node Certificates and Client Access: Root-Certificate Authorization have been followed, specify:
-
The remote cluster root certificate as
servercertfiles/ca.pem
. -
The client certificate as
servercertfiles/clientcertfiles/travel-sample.pem
. -
The client private key as
servercertfiles/clientcertfiles/travel-sample.key
.
-
-
If the procedures explained in Cluster Protection with Root, Intermediate, and Node Certificates and Client Access: Intermediate-Certificate Authorization have been followed, specify:
-
The remote cluster root certificate as
servercertfiles2/root/ca.pem
. -
The client certificate as
servercertfiles2/clients/clientuser.pem
. -
The client private key as
servercertfiles2/clients/private/clientuser.key
.
-
Configure Client Certificates for Java Clients
A Java client uses a keystore to access the certificates it requires for authentication. Certificate and keystore preparation is demonstrated by the procedures in the following two sections, which are:
-
Java Client Access: Root-Certificate Authorization. This creates a Java-client certificate signed by the cluster’s root certificate. As such, the procedure follows on from the server-certificate creation-process documented in Cluster Protection with Root and Node Certificates; and makes use of the directories and keys created there.
-
Java Client Access: Intermediate-Certificate Authorization. This creates a Java-client certificate signed by the cluster’s intermediate certificate. As such, the procedure follows on from the server-certificate creation-process documented in Cluster Protection with Root, Intermediate and Node Certificates; and makes use of the directories and keys created there.
Note that the assumptions specified for the examples above likewise apply to the Java client examples below.
Java Client Access: Root-Certificate Authorization
Proceed as follows:
-
Access the main working directory created in Cluster Protection with Root and Node Certificates, and create and access a new working directory for the Java client certificate to be created.
cd servercertfiles mkdir javaclient cd javaclient
-
Define two environment variables: one for the name of the keystore to be created, another for its password.
export KEYSTORE_FILE=my.keystore export STOREPASS=storepass
-
If necessary, install a package containing the
keytool
utility:sudo apt install openjdk-9-jre-headless
-
Generate the keystore. Note that the password you specify for the alias, by means of the
--keypass
flag, must be identical to the password you specify for the keystore, by means of the--storepass
flag. In this case, both passwords are specified as${STOREPASS}
; which resolves tostorepass
.keytool -genkey -keyalg RSA -alias selfsigned \ -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -validity 360 \ -keysize 2048 -noprompt -dname "CN=clientuser, OU=People, O=MyCompany, \ L=None, S=None, C=UA" -keypass ${STOREPASS}
Note that the
Common Name
for the certificate is specified asclientuser
, which is the username established on Couchbase Server, whose role-assignment is supportive of reading and writing data to thetravel-sample
bucket. -
Generate the certificate signing-request:
keytool -certreq -alias selfsigned -keyalg RSA -file my.csr \ -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt
-
Generate the client certificate, signing it with the root private key, and thereby establishing the root certificate’s authority:
openssl x509 -req -in my.csr -CA ../ca.pem \ -CAkey ../ca.key -CAcreateserial -out clientcert.pem -days 365
-
Add the root certificate to the keystore:
keytool -import -trustcacerts -file ../ca.pem \ -alias root -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt
-
Add the client certificate to the keystore:
keytool -import -keystore ${KEYSTORE_FILE} -file clientcert.pem \ -alias selfsigned -storepass ${STOREPASS} -noprompt
This concludes preparation of the Java client’s keystore.
Copy the file (in this case, my.keystore
) to a location on a local filesystem from which the Java client can access it.
A sample Java program, which accesses a keystore from a local filesystem, is provided in Authenticating against Couchbase Server.
Java Client Access: Intermediate-Certificate Authorization
Proceed as follows:
-
Access the main working directory created in Cluster Protection with Root, Intermediate, and Node Certificates, and create and access a new working directory for the Java client certificate to be created.
cd servercertfiles2 mkdir javaclient cd javaclient
-
Define two environment variables: one for the name of the keystore to be created, another for its password:
export KEYSTORE_FILE=my.keystore export STOREPASS=storepass
-
If necessary, install a package containing the
keytool
utility:sudo apt install openjdk-9-jre-headless
-
Note that the password you specify for the alias, by means of the
--keypass
flag, must be identical to the password you specify for the keystore, by means of the--storepass
flag. In this case, both passwords are specified as${STOREPASS}
; which resolves tostorepass
.keytool -genkey -keyalg RSA -alias selfsigned \ -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -validity 360 \ -keysize 2048 -noprompt -dname "CN=clientuser, OU=People, O=MyCompany, \ L=None, S=None, C=UA" -keypass ${STOREPASS}
Note that the Common Name for the certificate is specified as
clientuser
, which is the username established on Couchbase Server, whose role-assignment is supportive of reading and writing data to thetravel-sample
bucket. -
Generate the certificate signing-request:
keytool -certreq -alias selfsigned -keyalg RSA -file my.csr \ -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt
-
Generate the client certificate, signing it with the intermediate private key, and thereby establishing the intermediate certificate’s authority:
openssl x509 -req -in my.csr -CA ../servers/ca.pem \ -CAkey ../servers/ca.key -CAcreateserial -out clientcert.pem -days 365
Since the intermediate private key was encrypted, a prompt now appears, requesting entry of the pass phrase for the key:
Enter pass phrase for ../servers/ca.key:
Enter the pass phrase against the prompt.
-
Add the root certificate to the keystore:
keytool -import -trustcacerts -file ../root/ca.pem \ -alias root -keystore ${KEYSTORE_FILE2} -storepass ${STOREPASS2} -noprompt
-
Add the intermediate certificate to the keystore:
keytool -import -trustcacerts -file ../servers/ca.pem \ -alias root2 -keystore ${KEYSTORE_FILE2} -storepass ${STOREPASS2} -noprompt
-
Add the client certificate to the keystore:
keytool -import -keystore ${KEYSTORE_FILE2} -file clientcert.pem \ -alias selfsigned -storepass ${STOREPASS2} -noprompt
This concludes preparation of the Java client’s keystore.
Copy the file (in this case, my.keystore
) to a location on a local filesystem from which the Java client can access it.
A sample Java program, which accesses a keystore from a local filesystem, is provided in Authenticating against Couchbase Server.
Working with Supported Protocols
Couchbase Server client-libraries support client-side encryption, using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS). TLS versions 1.0 to 1.2 are supported by default. The highest-supported version of TLS is recommended.
Optionally, the minimum version of TLS can be set to be 1.2 or higher per cluster, using the following command:
curl -X POST -u Administrator:password http://127.0.0.1:8091/diag/eval -d "ns_config:set(ssl_minimum_protocol, 'tlsv1.2')"
Securing Client-Application Access
For an application to communicate securely with Couchbase Server, SSL/TLS must be enabled on the client side. Enablement requires a copy of the certificate used by Couchbase Server: this can be accessed from the Couchbase Web Console, as described in Root Certificate.
Note that if, at some point, this certificate gets regenerated on the server-side, a copy of the new version must be obtained, and the client re-enabled.
Cipher-Suite List-Configuration
A custom cipher-suite list can be created by setting the COUCHBASE_SSL_CIPHER_LIST
environment variable.
This is only supported on Linux operating systems, applies only to the Data Service, and requires that the variable be defined before Couchbase Server is started.
The environment variable can be set in either of the following ways:
-
Specify an explicit list of ciphers to be used. For example:
COUCHBASE_SSL_CIPHER_LIST="DHE-DSS-AES128-SHA,CAMELLIA128-SHA"
-
Specify ciphers by security-level. For example, to specify that all ciphers in both medium and high categories be used, enter the following:
COUCHBASE_SSL_CIPHER_LIST="MEDIUM,HIGH"
To display the ciphers available on your Linux platform for a particular security level, use the openssl
command.
For example, to display the high-level ciphers, enter the following:
openssl ciphers -v 'HIGH'
To check the current value of the COUCHBASE_SSL_CIPHER_LIST
environment variable, type printenv
at the Linux prompt: this returns a list of all currently set environment variables.