A newer version of this documentation is available.

View Latest

Manage Encryption Settings

    Establish and retrieve cluster-wide settings for the use of encryption and cipher-suites.

    HTTP method and URI

    GET /settings/security
    POST /settings/security


    Allows settings to be established for the use of encryption. This includes the encryption level, for node-to-node encryption within the cluster; UI disablement over insecure connections; TLS minimum version; and a list of server-accepted cipher suites.

    Curl Syntax

    curl -X GET -u <administrator>:<password>
    curl -X POST -u <administrator>:<password>
      -d disableUIOverHttp=<true|false>
      -d disableUIOverHttps=<true|false>
      -d clusterEncryptionLevel=<all|control>
      -d tlsMinVersion=<tlsv1|tlsv1.1|tslv1.2>
      -d honorCipherOrder=<true|false>
      -d cipherSuites=<list-of-accepted-cipher-suites>

    The syntax for the POST method includes the following:

    • disableUIOverHttp. Whether access to Couchbase Web Console should be disabled over http. Default is false, meaning that the console can be accessed over http.

    • disableUIOverHttps. Whether access to Couchbase Web Console should be disabled over https. Default is false, meaning that the console can be accessed over https.

    • clusterEncryptionLevel. Controls the level of encryption imposed on inter-node communications within the cluster. Can be either control (meaning that only server-management information is passed in encrypted form) or all (meaning that all information, including data handled by services, is passed in encrypted form). This can only be set after cluster encryption has been enabled: see Apply Node-to-Node Encryption.

    • tlsMinVersion. Specifies the minimum TLS version accepted by the cluster. Can be tlsv1, tlsv1.1, or tlsv1.2. The default is tlsv1.

    • honorCipherOrder. Specifies whether the cluster uses its own cipher-suite preference, rather than the client’s. The cluster’s list of accepted cipher-suites can be defined with the cipherSuites flag (see below). The default value of honorCipherOrder is true: a setting of false is not recommended, since insecure.

    • cipherSuites. Specifies a list of the cipher suites to be used by the cluster, in order of preference. The argument must be a list of cipher suites, each of which is supported by the underlying operating system. If the value for cipherSuites is an empty list ([]), this specifies that the Couchbase Server default cipher-suite list is to be used. Use openssl ciphers -v at the Linux command-line, to display the default list of cipher-suites available from the operating system.


    The GET method, if successful, gives 200 OK, and returns an object containing each configured parameter, with its current value. The POST method, if successful, gives 200 OK, and returns an empty array.

    For both methods, an incorrect URI gives 404 Object Not Found, with a Not found error message. Use of improper credentials gives 401 Unauthorized. An improper port number returns an error message such as Failed to connect, or Port number out of range.

    For the POST method, incorrectly specified parameters fail with 404 Bad Request, and return an error object that lists the errors in an array. For example, a call that incorrectly specifies every significant parameter-value returns an object such as the following:

      "errors": [
        "honorCipherOrder - Accepted values are 'true' and 'false'.",
        "cipherSuites - Invalid cipher suite names = TLS_RSA_WITH_AES_256_CBC_SHA33",
        "tlsMinVersion - Supported TLS versions are ['tlsv1.2','tlsv1.1',tlsv1]",
        "clusterEncryptionLevel - Cluster encryption level must be one of ['control', 'all'].",
        "disableUIOverHttps - Accepted values are 'true' and 'false'.",
        "disableUIOverHttp - Accepted values are 'true' and 'false'."

    Note additionally that an attempt to establish a value for clusterEncryptionLevel prior to the enablement of node-to-node encryption returns the following error-message: clusterEncryptionLevel - Can’t set cluster encryption level when cluster encryption is disabled. See Apply Node-to-Node Encryption, for details on how to enable.


    The methods and the URI can be used as shown below.

    Establish Encryption Settings

    The following establishes encryption settings for the cluster:

    curl  -u Administrator:password -v -X POST \ \
    -d disableUIOverHttp=true \
    -d clusterEncryptionLevel=control \
    -d tlsMinVersion=tlsv1.1 \
    -d 'cipherSuites=["TLS_RSA_WITH_AES_128_CBC_SHA", "TLS_RSA_WITH_AES_256_CBC_SHA"]'

    The disableUIOverHttp flag is given a value of true, indicating that access to Couchbase Web Console will be disabled over http. The disableUIOverHttps flag is not specified, meaning that access to Couchbase Web Console will not be disabled over https, by default. The clusterEncryptionLevel is specified as control, indicating that only server-management information is passed in encrypted form between cluster-nodes: note that this parameter can only be set after the node-to-node-encryption CLI command has been used to enable internal network-security for the cluster, as described in Apply Node-to-Node Encryption. The tlsMinVersion is specified as version 1.1. The honorCipherOrder parameter is not specified, meaning that it retains its default value of true; which ensures that the cluster’s own cipher-suites preference is used, rather than the client’s. The cipherSuites parameter is assigned a value that is a list of two cipher suites.

    If successful, the call returns an empty array:


    Retrieve Encryption Settings

    The GET /settings/security method and URI retrieve encryption settings for the cluster, as shown below. Note that the output is piped to the jq program, to enhance readability:

    curl  -u Administrator:password -v -GET \ | jq '.'

    If the call is successful, and occurs prior to any explicit settings by the administrator, the output is as follows:

      "disableUIOverHttp": false,
      "disableUIOverHttps": false,
      "tlsMinVersion": "tlsv1",
      "cipherSuites": [],
      "honorCipherOrder": true

    If explicit settings have been made — including the enablement of node-to-node encryption — the output might appear as follows:

      "disableUIOverHttp": false,
      "disableUIOverHttps": false,
      "tlsMinVersion": "tlsv1.1",
      "cipherSuites": [
      "honorCipherOrder": true,
      "clusterEncryptionLevel": "control"

    The returned object thus includes each of the settings — including clusterEncryptionLevel — with its current value. An array containing the established list of server-acceptable cipher suites is provided as the value of cipherSuites.