You are viewing the documentation for a prerelease version.

View Latest

Manage TLS

To support secure communications between nodes, clusters, and clients, Couchbase Server provides interfaces for the configuration of TLS and supportive cipher-suites.

TLS and Cipher-Suites

Transport Layer Security (TLS) is a protocol that provides security over a computer network. Couchbase Server supports the configuration of TLS, to secure communications between cluster-nodes, clusters, and external clients: this includes selection of an appropriate TLS version.

TLS supports multiple methods for exchanging keys, encrypting data, and authenticating message-integrity. Appropriate methods, supported by both participants in an intended networked communication, can be specified through selection of an appropriate cipher-suite, from defined lists of ones acceptable. By default, Couchbase Server uses a list of HIGH security cipher-suites. However, Couchbase Server also allows a customized list to be defined and used instead.

When a TLS connection is established between a client application and Couchbase Server — for example, using the secure port 18091 — a handshake occurs, as defined by the TLS Handshake Protocol. As part of this exchange, the client sends to the server the client’s own cipher-suite list; which specifies the cipher-suites that the client itself supports. A server-setting is provided to specify whether the server then conforms to its own or the client’s preference, in selecting a commonly acceptable cipher-suite to be used for the communication.

Once the selection has been made by Couchbase Server, Couchbase Server notifies the client of the selection, and the handshake process continues.

The TLS version and the cipher-suites to be used for the cluster can be managed with either the CLI or the REST API, as described below.

Set the Minimum TLS Version

Couchbase Server supports TLS versions 1.0, 1.1, and 1.2: the highest-supported version of TLS is recommended. The version can be set with either the CLI or the REST API.

Set the Minimum TLS Version with the CLI

To set the minimum TLS version with the CLI, use the setting-security command as follows:

/opt/couchbase/bin/couchbase-cli setting-security \
-c 10.143.192.101:8091 \
-u Administrator \
-p password \
--set \
--tls-min-version tlsv1.1

The set flag indicates that a value is to be set. The tls-min-version flag specifies the appropriate minimum TLS value, which can be tlsv1, tlsv1.1, or tlsv1.2; and is in this case specified as tlsv1.1.

If successful, the command returns the following success-message:

SUCCESS: Security settings updated

For more information, see setting-security

Set the Minimum TLS Version with the REST API

To set the minimum TLS version with the REST API use the POST /settings/security http method and URI, as follows:

curl  -u Administrator:password -v -X POST \
http://10.143.192.101:8091/settings/security \
-d 'tlsMinVersion=tlsv1.2'

The tlsMinVersion flag specifies the minimum TLS version to be used; which can be tlsv1, tlsv1.1, or tlsv1.2; and is in this case specified as tlsv1.2 If successful, the command gives a 200 OK message, and returns an empty array.

For more information, see Manage Encryption Settings.

Manage Cipher-Suite Lists

As described above, in TLS and Cipher-Suites, a custom cipher-suite list can be defined for Couchbase Server. Additionally, Couchbase Server can be configured to conform to either its own or the client’s preference, in selecting a commonly supported cipher-suite to be used for the communication. These tasks can be accomplished with either the CLI or the REST API, as described below.

Note that the CLI and the REST API only accept IETF RFC names, for cipher-suites. They do not support OpenSSL names.

Manage Cipher-Suites with the CLI

To manage cipher-suites with the CLI, use the setting-security command as follows:

/opt/couchbase/bin/couchbase-cli setting-security \
-c 10.143.192.101:8091 \
-u Administrator \
-p password \
--set \
--tls-honor-cipher-order 1 \
--cipher-suites TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA

The set parameter establishes use of the command to make settings. The tls-honor-cipher-order parameter-value is specified as 1, meaning that the server’s preference-order for cipher-suites will be used, rather than the client’s. (Note, however, that this setting is also the default; and so will remain established even if this parameter is not specified.) The cipher-suites parameter takes a value that is a list of cipher-suites to be used for the cluster. If the value for cipherSuites is an empty list (""), this specifies that the Couchbase Server default cipher-suite list is to be used.

If the call is successful, the following message is displayed:

SUCCESS: Security settings updated

For more information, see the reference page for setting-security. Note that this includes information on using the get parameter, in order to retrieve current settings.

Manage Cipher-Suites with the REST API

To manage cipher-suites with the REST API, use the GET and POST methods with the /settings/security URI.

To establish a cipher-suite list, and specify whether to honor the server’s or the client’s cipher-suite preference, enter the following:

curl  -u Administrator:password -v -X POST \
http://10.143.192.101:8091/settings/security \
-d honorCipherOrder=true \
-d 'cipherSuites=["TLS_RSA_WITH_AES_128_CBC_SHA", "TLS_RSA_WITH_AES_256_CBC_SHA"]'

The honorCipherOrder flag is specified as true, meaning that the server’s order of preference for cipher-suites, rather than the client’s, will be used. (Note, however, that true is the default; meaning that the server’s preference is used even if this parameter is not specified.) The value specified for the cipherSuites flag is a list of cipher-suites that can be used for the server, in order of preference. If the value for cipherSuites is an empty list ([]), this specifies that the Couchbase Server default cipher-suite list is to be used.

If successful, the call gives 200 OK, and returns an empty array.

For more information, see Manage Encryption Settings. Note that this page contains information on the GET method, and provides an example of its use.

Alternative Cipher-Suite List-Configuration

The recommended way of establishing a custom cipher-suite list is given above, for the CLI and the REST API. However, a custom list can also be achieved by setting the COUCHBASE_SSL_CIPHER_LIST environment variable: this legacy means of establishing a custom cipher-suite is only supported on Linux operating systems, and requires that the variable be defined before Couchbase Server is started.

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.