Configure On-the-Wire Security | Couchbase Docs (original) (raw)

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

HTTP Method and URI

GET /settings/security/[service-name]

POST /settings/security/[service-name]

Description

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 accepted cipher suites. Additionally, secure communication by means of TLS can be enforced across the cluster.

Note that information on setting an HTTP Secure Transport Header with the REST API is provided in Configure HSTS.

Curl Syntax

curl -X GET -u : http://:8091/settings/security/[service-name]

curl -X POST -u : http://:8091/settings/security/[service-name] -d disableUIOverHttp=<true|false> -d disableUIOverHttps=<true|false> -d disableWWWAuthenticate=<true|false> -d responseHeaders= -d allowedHosts= -d allowNonLocalCACertUpload=<true|false> -d clusterEncryptionLevel=<all|control|strict> -d tlsMinVersion=<tlsv1.2|tlsv1.3> -d honorCipherOrder=<true|false> -d cipherSuites= -d [scramSha1Enabled|scramSha256Enabled|scramSha512Enabled]=<true|false> -d passwordHashAlg=<argon2id|pbkdf2-hmac-sha512|SHA-1> -d argon2idTime== -d argon2idMem== -d pbkdf2HmacSha512Iterations= -d intCredsRotationInterval= -d validateNodeCertSan=<true|false> -d allowHashMigrationDuringAuth=<true|false>

The syntax for the GET and POST methods includes the following:

For an explanation of the relationships between per service and global settings, see On-the-Wire Security.

Enforcing TLS

Before applying the strict value to the clusterEncryptionLevel parameter:

Once strict has been applied to all nodes:

Responses

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 format. Expecting a list of ciphers.", "tlsMinVersion - Supported TLS versions are tlsv1.3, tlsv1.2.", "clusterEncryptionLevel - Cluster encryption level must be one of ["control","all","strict"]",, "disableUIOverHttps - Accepted values are 'true' and 'false'.", "disableUIOverHttp - Accepted values are 'true' and 'false'.", "disableWWWAuthenticate - 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 Manage Node-to-Node Encryption, for details on how to enable.

Examples

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

Establish On-the-Wire Settings, Globally

The following establishes a subset of on-the-wire settings globally:

curl -u Administrator:password -v -X POST
http://10.144.210.101:8091/settings/security
-d disableUIOverHttp=true
-d clusterEncryptionLevel=control
-d tlsMinVersion=tlsv1.2
-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 Manage Node-to-Node Encryption. The tlsMinVersion is specified as version 1.2. 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 Cluster-Wide Settings

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

curl -u Administrator:password -v -GET
http://10.144.210.101:8091/settings/security | jq '.'

If the call is successful, and some explicit settings have been made by the administrator, the output might appear as follows:

{ "disableUIOverHttp": false, "disableUIOverHttps": false, "disableWWWAuthenticate": false, "responseHeaders": [], "tlsMinVersion": "tlsv1.2", "cipherSuites": [ "TLS_RSA_WITH_AES_128_CBC_SHA", "TLS_RSA_WITH_AES_256_CBC_SHA" ], "honorCipherOrder": true, "allowNonLocalCACertUpload": false, "allowedHosts": [ "*.test.ubuntu", "127.0.0.1" ], "data": { "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.2", "honorCipherOrder": true, "supportedCipherSuites": [ "TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_GCM_SHA256", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", . . .

The global values of disableUIOverHttp, disableUIOverHttps, tlsMinVersion, and honorCipherOrder are thus displayed. Note also that a global value for cipherSuites has also been established.

The return object contains, in addition to global settings, a subdocument for each service. The truncated output shown here features values from the subdocument for the Data Service; which is shown to have its own values established for cipherSuites, tlsMinVersion, and honorCipherOrder. The read-only value for supportedCipherSuites for the service is also displayed.

Establish Per Service On-the-Wire Settings

The following call establishes global settings for tlsMinVersion and supportedCipherSuites, for the Data Service only:

curl -u Administrator:password -v -X POST
http://10.144.210.101:8091/settings/security/data
-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"]'

Note that the data path-parameter has been added to the URI, as the value of service-name, in order to specify the Data Service. If the call is successful, an empty array is returned.

To verify the new settings for the Data Service, use the GET method, again adding data to the URI:

curl -u Administrator:password -v -X GET
http://10.144.210.101:8091/settings/security/data | jq '.'

The returned output shows that the new settings have been successfully established:

{ "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", . . .

See Also

For more information on managing on-the-wire security-settings with the CLI, see the reference page for the setting-security command.

Information on setting an HTTP Secure Transport Header with the REST API is provided in Configure HSTS.

A conceptual overview of on-the-wire security is provided in On-the-Wire Security.