Manage 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 settings.
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.
-
Establishing the Cluster Encryption-Level.
-
Configuring TLS and Cipher-Suites.
-
Setting an HTTP Secure Transport Header (HSTS).
-
Enforcing TLS across the cluster.
These areas are described in detail in On-the-Wire Security, which should be read before the examples provided below are attempted.
On-the-Wire Security Settings
Three configurable, on-the-wire security settings are provided both globally and per service. They are as follows:
-
tlsMinVersion
. Specifies the minimum accepted TLS version: the server will not accept client connections with protocols below the level of the established, minimum version. The value can betlsv1
,tlsv1.1
,tlsv1.2
(the default), ortlsv1.3
. Note, however, thattlsv1
andtlsv1.1
are deprecated in Couchbase Server Version 7.2.This parameter can be established both globally and per service.
-
honorCipherOrder
. Specifies whether the service uses its own cipher-suite preference, rather than the client’s. The default value ofhonorCipherOrder
istrue
: a setting offalse
is not recommended, since insecure. -
cipherSuites
. Specifies a list of the cipher suites to be used by the service, in order of preference. The argument must be a list of cipher suites, each of which appears as a member of the array that is the value of the non-configurable supportedCipherSuites setting for the service.Note that Couchbase Server only accepts IETF RFC names, for cipher-suites: OpenSSL names cannot be used.
Additional on-the-wire security settings are provided for global configuration only — thus, these cannot be set per service:
-
disableUIOverHttp
. Whether access to Couchbase Web Console should be disabled over http. The default is that the console can be accessed over http. -
disableUIOverHttps
. Whether access to Couchbase Web Console should be disabled over https. The default is that the console can be accessed over https. -
disableWWWAuthenticate
. Whether to disable Couchbase Server’s responding to unauthenticated requests with WWW-Authenticate. The default is not to disable. -
clusterEncryptionLevel
. Controls the level of encryption imposed on cluster-communications. This can only be set after cluster encryption has been enabled: see Manage Node-to-Node Encryption. Its value can be any of the following:-
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
, meaningall
with only encrypted communication permitted between nodes and between the cluster and external clients. Note, however, that afterstrict
has been specified, communication that occurs entirely on a single node using the loopback interface (whereby the machine is identified as either::1
or127.0.0.1
) is still permitted in non-encrypted form.Applying
strict
as theclusterEncryptionLevel
has a number of significant consequences, which should be fully understood before proceeding. See Enforcing TLS, below.
-
-
Strict-Transport-Security
. Establishes 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. Three sub-settings must be established, which are:-
The duration of HTTPS-enforcement for this browser.
-
Whether the site’s subdomains are to be covered by the setting.
-
Whether the preload directive should be set; so that the policy is enforced before any communication takes place.
-
Enforcing TLS
Before applying the strict
value to the clusterEncryptionLevel
parameter:
-
Pause all Eventing functions on the cluster. (Resume them only after changes to node-to-node encryption and encryption-level been applied.) See eventing-function-setup.
-
Ensure all client applications and scripts are able to connect with TLS.
-
Ensure node-to-node encryption is enabled (see Manage Node-to-Node Encryption).
-
Ensure all XDCR replications are configured as fully secure (see Enable Fully Secure Replications).
Once strict
has been applied to all nodes:
-
Previously paused Eventing functions can be resumed.
-
The Eventing Service debugger port (9140) is not available (since non-TLS only). See Couchbase Server Ports.
-
The node cannot be added to a Version 6.0.x cluster. See TLS, Address-Family Restriction, and Node Addition.
Manage On-the-Wire Security, with the CLI
The Couchbase CLI allows cluster-wide on-the-wire security-settings to be retrieved; and allows the global settings to be established and modified.
Get Cluster-Wide Settings, with the CLI
The cluster-wide security configuration includes both global and per service settings. The current configuration can be retrieved with the setting-security command. This is shown by the following example. Note that the output is piped to the jq command, to optimise the output’s readability:
/opt/couchbase/bin/couchbase-cli setting-security \ -c 10.144.210.101:8091 \ -u Administrator \ -p password \ --get | jq '.'
If successful, the command returns output such as the following:
{ "disableUIOverHttp": false, "disableUIOverHttps": false, "disableWWWAuthenticate": false, "tlsMinVersion": "tlsv1", "cipherSuites": [], "honorCipherOrder": true, "data": { "supportedCipherSuites": [ "TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256", . . "TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256" ] }, "fullTextSearch": { "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", . . "TLS_CHACHA20_POLY1305_SHA256" ] }, "index": { "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", . . "TLS_CHACHA20_POLY1305_SHA256" ] }, "eventing": { "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", . . "TLS_CHACHA20_POLY1305_SHA256" ] }, "query": { "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", . . "TLS_CHACHA20_POLY1305_SHA256" ] }, "analytics": { "supportedCipherSuites": [ "TLS_AES_128_GCM_SHA256", "TLS_AES_256_GCM_SHA384", . . "TLS_EMPTY_RENEGOTIATION_INFO_SCSV" ] }, "backup": { "supportedCipherSuites": [ "TLS_RSA_WITH_RC4_128_SHA", "TLS_RSA_WITH_3DES_EDE_CBC_SHA", "TLS_RSA_WITH_AES_128_CBC_SHA", . . "TLS_CHACHA20_POLY1305_SHA256" ] }, "clusterManager": { "supportedCipherSuites": [ "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", . . "TLS_RSA_WITH_3DES_EDE_CBC_SHA" ] } }
The returned object contains attribute-value pairs that represent the current cluster-wide on-the-wire security configuration.
For information on the first three attributes shown in this example — disableUIOverHttp
, disableUIOverHttps
, and disableWWWAuthenticate
— see the CLI reference page for setting-security; and the REST reference page Configure On-the-Wire Security.
The tlsMinVersion
is shown as set to tlsv1
.
The value of honorCipherOrder
is the default, which is true
.
No custom cipher-suite list has been provided as the value of cipherSuites
: accordingly, the array is empty.
The remaining attributes in the object correspond to the services for which on-the-wire security can be configured: data
, fullTextSearch
, index
, eventing
, query
, analytics
, backup
, and clusterManager
.
Currently, each contains a single attribute-value pair, specifying supportedCipherSuites
.
The value of the list, in each case, is a read-only list of cipher-suites (truncated, in the output-display provided above), which is for informational purposes: if a cipher-suite list is to be custom-configured for the service, it must only feature cipher-suites included in the list that is value of supportedCipherSuites
.
Note that when custom-settings are made either globally or per service, further attribute-value pairs are added to the corresponding subdocuments, and are duly displayed when settings are retrieved.
Set the Minimum TLS Version Globally, with the CLI
To set the minimum TLS version globally, with the CLI, use the setting-security command as follows:
/opt/couchbase/bin/couchbase-cli setting-security \ -c 10.144.210.101:8091 \ -u Administrator \ -p password \ --set \ --tls-min-version tlsv1.2
The set
flag indicates that a value is to be set.
The tls-min-version
flag specifies the appropriate global-minimum TLS value, which can be tlsv1
, tlsv1.1
, tlsv1.2
, or tlsv1.3
; and is in this case specified as tlsv1.2
.
If successful, the command returns the following success-message:
SUCCESS: Security settings updated
For more information, see setting-security
Set a Global Cipher-Suite List, with the CLI
The global cipher-suite list for the cluster can be established, by means of the CLI.
Enter the following command:
/opt/couchbase/bin/couchbase-cli setting-security \ -c 10.144.210.101:8091 \ -u Administrator \ -p password \ --tls-honor-cipher-order 1 \ --cipher-suites TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA \ --set
This establishes that the server’s order of cipher-suites is to be honored, and specifies a cipher-suite list of two ciphers.
If the call is successful, the following message is displayed:
SUCCESS: Security settings updated
Note that since the REST API can be used to establish a cipher-suite list for each individual service, a system of preferences is maintained by Couchbase Server, to determine which setting is used by each service, when multiple settings have been established. For information, see Establishing Cipher-Suite Lists.
Establish Other Global Settings, with the CLI
As described above, the CLI can also be used to establish global settings for
disableUIOverHttp
, disableUIOverHttps
, disableWWWAuthenticate
, and clusterEncryptionLevel
.
It can also be used to establish HSTS; by means of the hsts-max-age
, hsts-preload-enabled
, and hsts-include-sub-domains-enabled
parameters.
For information, see the reference page for the setting-security command.
Manage On-the-Wire Security with the REST API
The Couchbase REST API allows cluster-wide on-the-wire security-settings to be retrieved; and allows global and per service settings to be established and modified.
Use the GET
and POST
HTTP methods, with the /settings/security/[service-name]
URI.
For more information on all REST API calls shown here, see the reference page Configure On-the-Wire Security.
Get Cluster-Wide Settings, with the REST API
The following expression uses GET /settings/security
to return the current, cluster-wide on-the-wire security settings, for the cluster:
curl -u Administrator:password -v -X GET \ http://10.144.210.101:8091/settings/security | jq
If successful, the call returns 200 OK
, and an object that contains the current settings.
For an example of this object, and a description of its elements, see Get Cluster-Wide Settings, with the CLI, above.
Set the Minimum TLS Version Globally, with the REST API
To set the minimum TLS version globally, with the REST API, use the POST /settings/security
method and URI, as follows:
curl -u Administrator:password -v -X POST \ http://10.144.210.101:8091/settings/security \ -d 'tlsMinVersion=tlsv1.2'
The tlsMinVersion
flag specifies the global-minimum TLS version to be used; which can be tlsv1
, tlsv1.1
, tlsv1.2
(which is the default), or tlsv1.3
; and is in this case explicitly specified as tlsv1.2
.
If successful, the command gives a 200 OK
message, and returns an empty array.
Set a Global Cipher-Suite List, with the REST API
To establish a global 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.144.210.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 ([]
), no global cipher-suite list is established: for information on default cipher-suite lists used by individual services, see On-the-Wire Security.
If successful, the call gives 200 OK
, and returns an empty array.
Establish Other Global Settings, with the REST API
As described above, the REST API, using the /settings/security
URI, can also be used to establish global settings for
disableUIOverHttp
, disableUIOverHttps
, disableWWWAuthenticate
, and clusterEncryptionLevel
.
For information, see Configure On-the-Wire Security.
For information on setting an HTTP Secure Transport Header with the REST API, see Configure HSTS.
Configure On-the-Wire Security Per Service, with the REST API
Using the REST API, the tlsMinVersion
, honorCipherOrder
, and cipherSuites
parameters can be configured per service.
This requires that the appropriate service-name
be appended to the URI.
The value of service-name
can be any one of the following: data
(Data Service), fullTextSearch
(Search Service), index
(Index Service), eventing
(Eventing Service), query
(Query Service), analytics
(Analytics Service), backup
(Backup Service), clusterManager
(Cluster Manager).
For example, the following call sets these parameters for the Data Service alone:
curl -u Administrator:password -v -X POST \ http://10.144.210.101.:8091/settings/security/data \ -d honorCipherOrder=true \ -d tlsMinVersion=tlsv1.3 \ -d 'cipherSuites=["TLS_RSA_WITH_AES_128_CBC_SHA", "TLS_RSA_WITH_AES_256_CBC_SHA", "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"]'
If successful, the call returns an empty array.
To check the current settings, use the GET
method, with the /settings/security/data
URI, as follows:
curl -u Administrator:password -v -X GET \ http://10.144.210.101:8091/settings/security/data | jq
If successful, this call returns 200 OK
, and an object containing the current settings for the Data Service.
For example:
{ "cipherSuites": [ "TLS_RSA_WITH_AES_128_CBC_SHA", "TLS_RSA_WITH_AES_256_CBC_SHA", "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" ], "tlsMinVersion": "tlsv1.3", "honorCipherOrder": true, "supportedCipherSuites": [ "TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256", . . .
The current cipherSuites
list for the service is thus shown to have been appropriately updated.
See Also
For more information on the REST API, see Configure On-the-Wire Security and Configure HSTS. For more information on the CLI, see the reference page for the setting-security command. A conceptual overview of on-the-wire security is provided in On-the-Wire Security.