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 explains how client certificates can be prepared for a Java client. It also provides information on TLS levels, and on supported ciphers.

For a list of Couchbase-Server ports that provide secure connectivity to clients, see Connectivity.

Configure Certificates for a Java Client

Once the root certificate for a Couchbase Server-node has been deployed, a Java client can authenticate by means of an appropriately prepared keystore, and so gain access to the Data, Query, and Search Services.

Proceed as follows. Note that these instructions use the Ubuntu 16 environment previously configured in Configure Server Certificates.

  1. Define environment variables for the name of the keystore to be created, and its password.

    export KEYSTORE_FILE=my.keystore
export STOREPASS=storepass

  2. If necessary, install a package containing the keytool utility:

    sudo apt install openjdk-9-jre-headless

  3. Within the top-level, SSLCA directory that you created, generate the keystore:

    keytool -genkey -keyalg RSA -alias selfsigned \
-keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -validity 360 -keysize 2048 \
-noprompt  -dname "CN=${USERNAME}, OU=None, O=None, L=None, S=None, C=US" -keypass ${STOREPASS}

  4. Generate the certificate signing-request:

    keytool -certreq -alias selfsigned -keyalg RSA -file my.csr \
-keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt

  5. Generate the client certificate, signing it with the intermediate private key:

    openssl x509 -req -in my.csr -CA ./${INT_DIR}/${INTERMEDIATE}.pem \
-CAkey ./${INT_DIR}/${INTERMEDIATE}.key -CAcreateserial -out clientcert.pem -days 365

  6. Add the root certificate to the keystore:

    keytool -import -trustcacerts -file ./${ROOT_DIR}/${ROOT_CA}.pem \
-alias root -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt

  7. Add the intermediate certificate to the keystore:

    keytool -import -trustcacerts -file ./${INT_DIR}/${INTERMEDIATE}.pem \
-alias int -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt

  8. 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.

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. To perform enablement, you must acquire a copy of the certificate used by Couchbase Server, and then follow the steps appropriate for your client. Access the certificate from the Couchbase Web Console: see Root Certificate. Note that if, at some point, this certificate gets regenerated on the server-side, you must obtain a copy of the new version, and re-enable the client.

When a TLS connection is established between a client application and Couchbase Server running on port 18091, a handshake occurs, as defined by the TLS Handshake Protocol. As part of this exchange, the client must send to the server a cipher-suite list; which indicates the cipher-suites that the client supports, in order of preference. The server replies with a notification of the cipher-suite it has duly selected from the list. Additionally, symmetric keys to be used by client and server are selected by means of the RSA key-exchange algorithm.

Overriding Supported Ciphers

Couchbase Server uses ciphers that are accepted by default by OpenSSL. The default behavior employs high-security ciphers, built into OpenSSL.

You can override this selection, by setting the COUCHBASE_SSL_CIPHER_LIST environment variable — this must be performed before starting Couchbase Server. 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.