Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

On-the-Wire Security

      +
      To support secure communications between nodes, clusters, and clients, Couchbase Server provides interfaces for the configuration of on-the-wire security.

      Understanding On-the-Wire Security

      The interfaces provided by Couchbase Server for configuring on-the-wire security apply to the following areas:

      • Accessing the UI provided by Couchbase Web Console. This can be disabled, for the whole cluster; over either HTTP or HTTPS, or over both.

      • Establishing the Cluster Encryption-Level. The level of encryption imposed on inter-node communications within the cluster can be configured. This can be:

        • control, meaning that server-management information passed between nodes is passed in encrypted form.

        • all, meaning that all information passed between nodes, including data handled by services, is passed in encrypted form.

        • strict, meaning all with only encrypted communication permitted between nodes and between the cluster and external clients. This is available only in Couchbase Server Version 7.0.2 and later. Note that after strict has been specified, communication that occurs entirely on a single node using the loopback interface (whereby the machine is identified as either ::1 or 127.0.0.1) is still permitted in non-encrypted form.

          The cluster encryption-level can only be configured after cluster encryption itself has been enabled: see Node-to-Node Encryption.

          Before establishing the encryption-level as strict, see the information provided in Enforcing TLS.

      • Configuring TLS and Cipher-Suites. This includes establishing the server’s minimum TLS version; determining whether the server’s or the clients' cipher-order is used in a given communication; and configuring the list of cipher-suites that is accepted by the server. These values can be configured either globally (for the whole cluster), or on a per service basis. Details are provided immediately below.

      • Setting an HTTP Secure Transport Header (HSTS); so as to inform the Web-Console browser never to load a site using HTTP; and instead, to automatically convert all access-requests from HTTP to HTTPS. This is available only in Couchbase Server Version 7.0.2 and later.

      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.

      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.

      Configuring TLS and Cipher-Suites

      Configuration for TLS and cipher-suites includes establishing the server’s minimum TLS version; determining whether the server’s or the clients' cipher-order is used in a given communication; and configuring the list of cipher-suites that is accepted by the server. Such settings can be established either globally (that is, for the entire cluster), or per service. (Note that the other on-the-wire security settings — for console-access and encryption-level — are global-only; and cannot be set for an individual service.) A service can be any of the Couchbase Server Services; it can also be the Cluster Manager.

      The relationships between global and per service settings for TLS and cipher-suites are described in the following subsections.

      Establishing the Minimum TLS-Version

      The minimum TLS version can be established either globally or per service: the server will not accept client connections with protocols below the level of the established, minimum version.

      The minimum version can be established globally and for all services as tlsv1, tlsv1.1, or tlsv1.2. A value of tlsv1.3 can be established for the following services: Data, Search, Index, Query, Eventing, Analytics, and Backup; it cannot be established either globally or for the Cluster Manager. See Cipher-Suite Configuration Limitations, below, for further information.

      The cluster-wide default value for the minimum TLS version is tlsv1.2: this is used by a service if no value has been specified for that service, and no global value has been specified.

      If a particular minimum TLS-version is specified for a given service, that service uses its specified value. If no TLS-version has been specified for a given service, but a global value has been specified, the service uses the global value.

      Establishing Cipher-Suite Preference

      This determines, when secure communication is required between server and client, whether the cipher-suite list configured for the server is that to be used; or whether that configured for the client is to be used. The server’s preference is strongly recommended to be used, since secure: however, preference can be delegated to the client, if required.

      The default value — both globally and per service — is that the server’s preference is used: this, therefore, is the case if no cipher-suite preference value is specified either for a given service or globally.

      If a particular cipher-suite preference value has been specified for a given service, the service uses that value. If no cipher-suite preference value has been specified for a given service, and a value has been specified globally, the service uses the global value.

      Establishing Cipher-Suite Lists

      Each service is pre-configured with a list of supported cipher-suites. This list can be inspected as a read-only value (see Get Cluster-Wide Settings, with the CLI, for an example). Only those cipher-suites included in this list can be used by the service.

      A custom list of cipher-suites can be configured per service. The custom list should be a subset of those cipher suites included in the pre-configured list of supported cipher-suites. Any cipher-suites included in a per-service or global list that do not appear on the pre-configured list of supported cipher-suites for that service are ignored by the service.

      A custom list of cipher-suites can also be configured globally. The relationships between the per-service custom and pre-configured lists, and the global list, are as follows:

      • If a custom list of cipher-suites is established for a given service, the service uses that list.

      • If no custom list of cipher-suites is established for a given service, but a global list is established, the service uses the global list.

      • If no custom list of cipher-suites is established for a given service, and no global list is established, the service uses a list of HIGH security cipher-suites.

      There is no global, pre-configured list of supported cipher-suites.

      Cipher-suites are used by a service in the order in which the cipher-suites appear in the list established for the service. The order of cipher-suites in a custom list may be varied from that of the pre-configured list of supported cipher-suites for the service, except in the case of 1.3 cipher-suites when used by the Index, Search, Query and Backup services: see Cipher-Suite Configuration Limitations, below, for information.

      Cipher-Suite Configuration Limitations

      The following limitations apply to cipher-suite configuration.

      TLS 1.3 Cipher-Suite Limitations

      As indicated above, only the Data, Search, Index, Query, Eventing, Analytics, and Backup services can use TLS 1.3 cipher-suites. TLS 1.3 cipher-suites cannot be used by the Cluster Manager.

      Of the services that can use TLS 1.3 ciphers, only the Data and Analytics services support the custom-configuration of TLS 1.3 ciphers — custom-configuration of ciphers means the selection of a subset of available ciphers for a custom cipher-suite list, and the specifying of the selected ciphers in the subset in any order judged appropriate.

      The remaining services that can use TLS 1.3 — Search, Index, Query, and Backup — do not support custom-configuration of TLS 1.3 ciphers. This means that, for these services:

      • A custom cipher-suite list will always implicitly include all the TLS 1.3 cipher-suites in the list of supported cipher-suites for that service: none of those TLS 1.3 cipher-suites can be omitted.

      • The order of the 1.3 cipher-suites is determined based on available hardware.

      • If a client is able to use 1.3 cipher-suites, the service and client can communicate only by means of one of the listed 1.3 cipher-suites.

      TLS 1.2 Cipher-Suite Limitation with HTTP/2

      If the HTTP/2 protocol is to be used with TLS 1.2, the cipher-suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 must be specified in any custom list. If this cipher-suite is not present, HTTP/1 or HTTP/1.1 are used, instead of HTTP/2. For information, see Section 9.2.2 of the Hypertext Transfer Protocol Version 2 (HTTP/2).

      Also, for information on cipher-suites prohibited by HTTP/2, see Appendix A of the same document.

      Establishing an HTTP Secure Transport Header

      Setting an HTTP Secure Transport Header (HSTS) informs the Web-Console browser never to load a site using HTTP; and instead, to automatically convert all access-requests from HTTP to HTTPS. Only the Strict-Transport-Security header is supported.

      Configuring On-the-Wire Security-Parameters

      The parameters provided by Couchbase Server for on-the-wire security can be configured by means of either the CLI or the REST API. See Manage On-the-Wire Security, for information.