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.

    Handling Client Certificates

    Couchbase Server supports authentication based on client-side certificates. An example of client-side certificate-generation is provided in Provide Certificate-Based Authentication for a Java Client; and an example of how such a certificate can be referenced by a client-program is provided in Authenticating a Java Client by Certificate.

    Clients' use of certificates can be enabled, disabled, or made mandatory for the cluster; by means of the Client Certificate screen, which is accessible from the Client Certificate tab, near the top of the main Security screen of Couchbase Web Console.


    Select Disable to disable certificate-based authentication: this means that authorization can only occur by means of username and password (for Couchbase-defined users) or username (for LDAP-defined users). Select Enable to make certificate-based authentication optional for clients. Select Mandatory to make certificate-based authentication a requirement for clients (except in the case of manual login, at the Couchbase Web Console).

    Appropriate paths, prefixes, and delimiters can be specified: for detailed information on certificate-identity extraction, see Certificate-Based Authentication.

    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:

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

    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. For example:

    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.

    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:

    • Specify ciphers by security-level. For example, to specify that all ciphers in both medium and high categories be used, enter the following:


    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.

    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.