A newer version of this documentation is available.

View Latest

Encryption on the Wire

    Data on the wire needs to be protected from eavesdropping. Therefore, Couchbase Server uses SSL/TLS to encrypt data passed between clients and servers, and between data centers.

    Securing Administrator-Access

    Full Administrators can configure administrative access so that client-communications with Couchbase Server are encrypted, by means of SSL/TLS. This protocol is fully supported by the Couchbase client-libraries for both the Couchbase Web Console and the REST API.

    When securely initialized, Couchbase Server generates a self-signed certificate for the initial node, which is then propagated throughout all the nodes in the cluster. In terms of security-strength, this certificate is presumed to be adequate for your pre-production activities: optionally, however, you can switch to an X.509 certificate, before you deploy your application into production. See Configuring X.509.

    Connecting Securely to the Console

    The Couchbase Web Console can be accessed over HTTPS, on port 18091. Since it is protected by SSL/TLS, this connection is secure.

    For example, if you have established the Couchbase Web Console on http://`servername:8091`, you can access it securely on https://`servername:18091`.

    Performing Certificate Verification

    To verify which certificate your cluster is currently using, access the Couchbase Web Console, and left-click on the Security tab, in the navigation-bar at the left-hand side:


    This brings up the Security screen. When it appears, left-click on the Root Certificate tab, which is located on the horizontal control-bar, near the top (note that you must be in the role of Full Administrator, to see and access the Root Certificate):


    This displays the Root Certificate View, which features the self-signed root certificate, in a scrollable pane:

    self signed certNewUI

    Note that the certificate can be regenerated or replaced, using the Encryption On-the-Wire API, or CLI commands for certificate-management.

    Disabling Non-Secure Console Access

    If you wish to force Administrators to log into the UI over an encrypted channel, and so use port 18091, you can disable Couchbase Web Console access on port 8091. This only affects console access, and does not prevent REST requests from continuing to use 8091, non-securely.

    The following REST API method disables the Couchbase Web Console on port 8091:

    curl -u Administrator:password http://localhost:8091/settings/security -d disableUIOverHttp=true

    To re-enable Couchbase Web Console access on port 8091:

    curl -u Administrator:password http://localhost:8091/settings/security -d disableUIOverHttp=false

    The command line can also be used for this disabling step, although not (in Couchbase Server 5.0) to reverse it:

    $ couchbase-cli setting-security -c <servername> -u Administrator \
       -p password --disable-http-ui

    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, you can set the minimum version of TLS to be 1.2 or higher, using the following command:

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

    This command should be executed per cluster; and requires Full Administrator privileges.

    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, as shown above. 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.

    Securing SDK Access

    All the Couchbase SDKs support SSL/TLS encryption: Java, .NET, Node.js, PHP, Python, C, and Go. Each must use the Couchbase network port 11207, for secure communication.

    Securing View Access

    Port 18092 must be used for secure view access. Thus: https://`servername:18092`

    Securing Query Access

    The REST endpoint for secure access to N1QL queries is: https://`servername:18093/query/service`

    Securing FTS Access

    To use Full Text Search securely, port 18094 must be specified. Here is a REST API example from the Full Text Search Reference page, reworked for encrypted access:

                curl -u Administrator:password https://localhost:18094/api/index/myFirstIndex/count

    Securing Backups

    Both cbbackup and cbbackupmgr can use the secure port: https://`servername:18091`

    Overriding Supported Ciphers

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

    • AES256-SHA

    • AES128-SHA

    • DES-CBC3-SHA

    You can override this selection, by setting the following environment variable before starting Couchbase:

    COUCHBASE_SSL_CIPHER_LIST= <list-of-ciphers-to-accept>

    If you wish to include both medium and high-security ciphers in your installation, you can define the environment variable as follows:


    For macOS, the ciphers so specified would be the following

    • SEED-SHA

    • AES256-SHA

    • AES128-SHA

    • DES-CBC3-SHA

    • RC4-SHA

    • RC4-MD5

    Moving Data Between Server-Nodes

    Couchbase Server replicates data across a cluster, to ensure the data’s high availability. When you encrypt documents, replica copies are duly transmitted and stored in encrypted form.

    For added security, use IPSec on the network that connects the Couchbase Server-nodes. Note that IPSec has two modes: tunnel and transport. Transport mode is recommended, as it is the easier of the two to set up, and does not require the creation of 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.

    Moving Data Between Data Centers

    To protect data transmitted between data centers, you can use TLS to encrypt your XDCR connection. When you enable TLS in XDCR, Couchbase Server uses TLS certificates. TLS versions 1.0 to 1.2 are supported. All traffic between source and destination-datacenters is encrypted. Note that the encryption causes a slight increase in the CPU load.

    You are recommended to rotate the XDCR certificates periodically, in accordance with your organization’s security policy.

    For information on securing XDCR, see XDCR Data Security.