A newer version of this documentation is available.

View Latest

Encryption on the Wire

Couchbase encrypts the data moving between client and server, between servers within a cluster, and between data centers.
Starting with version 4.0, Couchbase Server uses the TLS protocol by default for encrypted interactions. The server supports both TLS 1.0-1.2 for XDCR. Which version it uses depends on the source and target clusters.

Data moving between client and server needs to be protected from any attackers eavesdropping on the connection. Couchbase Server enables encrypted data access using SSL/TLS for client-server communications.

Secure Administrative Access

The Full Administrators can configure encrypted administrative access using SSL/TLS to enable HTTPS access for the Couchbase Web Console and the REST API.

Couchbase Server client libraries support client-side encryption using the SSL/TLS protocol by encrypting data in-flight between the client and the server. This encryption establishes a secure channel between the remote machine and the server.

By default, Couchbase Server generates a self-signed certificate for the initial node, which is propagated throughout the server nodes in the cluster. You can switch over from a self-signed to an X.509 certificate before you deploy your application into production.

To set up certification, see Configuring X.509.

Connecting to the Couchbase Web Console

While an administrative console is typically protected via an HTTPS connection, the new administrative access on port 18091 allows connection to the Couchbase Web Console over SSL/TLS, which is enabled by default.

To talk over SSL/TLS to the Couchbase Web Console, connect to the following URL with your web browser: https://couchbase_server:18091

Verifying the cluster’s certificate

To verify which certificate your cluster is currently using:

  1. Select Security  Root Certificate.

    Only the Full Administrator role can see the Root Certificate tab in the Couchbase Web Console UI.
    self signed cert
  2. The Root Certificate link shows that a self-signed certificate has been deployed across the cluster. This certificate can be regenerated or replaced using Encryption On-the-Wire API or CLI commands for managing certificates.

Viewing the SSL Certificate Used in the Web Browser

  1. Connect to Couchbase Server through an encrypted port to communicate on a secure channel (18091 for REST HTTP or 18092 for CAPI HTTP).

  2. Log in with the Full Administrator’s name and password.

  3. Once you are logged in, the URL shows a secure connection.

The following section shows an example URL of a secure connection using the Safari web browser.

Disabling the Couchbase Web Console on Port 8091

If you would like to force Administrators to log in to the UI over an encrypted channel, you can disable the UI over the 8091 HTTP port, so that administrators can only access the administrative web console over port 18091.

This setting does not disable port 8091 completely since port 8091 is an important Couchbase port that also handles REST requests in addition to the administrative web console.

To disable the Couchbase Web Console over port 8091:

curl -X POST -u Administrator:password \
            -d 'ns_config:set(disable_ui_over_http, true)'

To re-enable the Couchbase Web Console over port 8091:

curl -X POST -u Administrator:password \
            -d 'ns_config:set(disable_ui_over_http, false)'

Secure Data Access

Couchbase Server client libraries support client-side encryption using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS).

Couchbase Server and SDKs support TLS v1.0 - 1.2 by default. Which version you use depends on the client and server version. Older versions might still use SSL, and should be upgraded to newer version of the SDK.

Starting with Couchbase Server version 4.1.1, you can set the minimum version of TLS 1.2 or higher using the following command:

curl -X POST -u Administrator:password -d "ns_config:set(ssl_minimum_protocol, 'tlsv1.2')"

The TLS 1.2 setup command can be executed per cluster. The command has to be invoked using full administrator privileges.

For changes to be affective on port 18092, cluster restart is needed. For changes to be affective just on port 18091, no cluster restart is needed.

Encryption for data access is performed through client-server communication and view access.

SSL/TLS Based Client-server Communication

Couchbase Server client libraries support client-side encryption using the SSL/TLS protocol by encrypting data in-flight between the client and the server. For Couchbase clients released after version 2.0, Couchbase Server provides secure client-server communication that does not require configuration.

When a TLS connection is established, a handshaking, known as the TLS Handshake Protocol, occurs. Within this handshake, a client hello (ClientHello) and a server hello (ServerHello) message are passed (RFC 5246). First, the client sends a cipher suite list, a list of the cipher suites that it supports, in order of preference. Then the server replies with the cipher suite that it has selected from the client cipher suite list. Check whether your clients support TLS.

The key-exchange algorithms like RSA and Elliptic Curve Cryptography (ECC) govern the way the server and client will determine which symmetric keys to use during a TLS session. The TLS protocol supports both RSA and ECC, however for Couchbase Server, it supports only RSA keys.

To enable SSL/TLS on the client side, you need to get a certificate from Couchbase Server and then follow the steps appropriate to the client you are using.

You can obtain a self-signed, server -generated certificate using the Couchbase Web Console. Navigate to Settings  Certificate  Show certificate and copy the certificate.

If the self-signed certificate obtained via the Couchbase Web Console is regenerated, you must obtain a new one.

SSL/TLS Support by Clients

The following clients support SSL/TLS: Java, .NET, Node.js, PHP, Python, C, and Go.

Use the Couchbase network port 11207 for data communication between the client and the data nodes using SSL/TLS.

SSL/TLS Based View Access

A new port 18092 is established for view access: https://couchbase_server:18092

Supported Ciphers

Couchbase Server uses the ciphers that are accepted by default by OpenSSL.The default is to have high-security ciphers built in with openSSL. For example, on the MAC OS these are:

  • AES256-SHA

  • AES128-SHA


You can override this selection by setting the environment variable before starting Couchbase as follows:

COUCHBASE_SSL_CIPHER_LIST= <list of ciphers to accept>

Set the variable to COUCHBASE_SSL_CIPHER_LIST= MEDIUM, HIGH to include only medium- and high-security ciphers for your installation.

For example, on the MAC OS these are:


  • AES256-SHA

  • AES128-SHA


  • RC4-SHA

  • RC4-MD5

Data Moving Between Servers within a Cluster

Your data has to be available all the time (24x7x365), and your applications must be able to access that data even if any of the servers in the cluster dies. To ensure high availability, Couchbase Server replicates data within the cluster and across data centers.

If you encrypt all your sensitive data in the documents, the replica copies will be transmitted as is (encrypted) and stored. For added security, it is a good security practice to use IPSec on the network that connects the Couchbase server nodes.

IPSec has two modes: tunnel mode and transport mode. We recommend using IPSec with the transport mode, as it is easier to setup than the tunnel mode and does not require creating tunnels between all pairs of Couchbase nodes.

To learn more about setting up transport mode IPSec for Couchbase, see the blog "Configuring IPsec for a Couchbase Cluster".

Data Moving Between Data Centers

To protect sensitive data transmitted among data centers in different geo-locations, you can use TLS to encrypt your XDCR connection. When you enable TLS in XDCR, Couchbase Server uses TLS certificates, and all traffic between source and destination datacenters will be encrypted. The encryption causes a slight increase in the CPU load.

It is a good security practice to rotate the XDCR certificates periodically, as per your organization’s security policy.