Configuring System Secrets

By means of the REST API, System Secrets can be configured, and the current configuration can be retrieved.

HTTP Methods and URIs

GET /nodes/self/secretsManagement

POST /node/controller/secretsManagement

Description

Configures system secrets; which comprises the master password, data keys, key storage, and the location of key-control scripts.

The Full Admin, Local User Security Admin, or External User Security Admin role is required.

Curl Syntax

curl -X GET http://<ip-address-or-hostname>:8091/nodes/self/secretsManagement/encryptionService
  -u <username>:<password>

curl -X POST http://<ip-address-or-hostname>:8091/node/controller/secretsManagement/encryptionService
  -u <username>:<password>
  -H <header>
  [-d <option>=<value>]*

The Content-Type can be either application/json or application/x-www-form-urlencoded. (Note that application/x-www-form-urlencoded can be omitted in curl commands, since used by default.)

Each option and associated value is described below.

keyEncrypted. Whether data keys should be encrypted by means of the master password. The value can be either true (the default) or false.
keyPath. Specifies whether the data keys are stored at the default or at a custom location. The value can be either auto (which is the default) or custom. If the value is auto, the default location is used. If the value is custom, the path provided by customKeyPath is used. Note that this option is used only if keyStorageType has the value file.
customKeyPath. A file-path that specifies a custom location at which the data keys are stored. This file-path is used only if the value of keyPath is custom.
keyStorageType. The value can be file (which is the default) or script. If the value is file, the system stores the data keys in a file. If the value is script, a user-specified script is called, when keys are to be written, read, or deleted. These scripts must be specified by writeCmd, readCmd, and deleteCmd, respectively.
passwordSource. The value can be env (which is the default) or script. If the value is env, the master password is read from the environment variable specified by passwordEnv. If the value is script, the master password is provided by the script specified by passwordCmd.
passwordEnv. The name of the environment variable from which the master password is read (provided that the value of passwordSource is env). By default, the value of passwordEnv is CB_MASTER_PASSWORD.
passwordCmd. The script to be executed for provision of the master password. This script is only executed when the value of passwordSource is script.

This script is executed when the node is started. It may also be executed in the event either of a node-reconfiguration or of an anomaly. The script must exit with status code 0 — otherwise, an error occurs. The script is expected to write the master password to standard output.
passwordState. Shows the state of the encryption-service master password and data keys. The value can be:
- default. The encryption password is not set.
- user_configured. The master password is set
- password_not_used. The data keys are not encrypted.
This is a read-only setting, and so cannot be used with the POST method.
readCmd. The script to be executed for the reading of data keys (when the value of keyStorageType is script).
writeCmd. The script to be executed for the writing of data keys (when the value of keyStorageType is script).
deleteCmd. The script to be executed for the deletion of data keys (when the value of keyStorageType is script).

Responses

For GET and POST, success returns 200 OK, and an object containing the current settings.

Failure to authenticate returns 403 Bad Request, and an error message such as the following:

{
  "message": "Forbidden. User needs the following permissions",
  "permissions": [
    "cluster.admin.security!write"
  ]
}

An incorrectly expressed URI returns 404 Object Not Found. An incorrectly formatted payload returns 400 Bad Request.

If an invalid or inaccessible script is specified for reading the master password for encryption-key handling, the call fails with 400 Bad Request, and a corresponding error message.

Examples

The following examples demonstrate different ways in which secrets management can be configured.

Retrieving the Current Configuration

The following command retrieves the current configuration. Output is piped to the jq command, to facilitate readability.

curl -v -X GET http://localhost:8091/nodes/self/secretsManagement/encryptionService \
-u Administrator:password | jq '.'

Output takes the following form:

{
  "keyEncrypted": true,
  "keyPath": "auto",
  "keyStorageType": "file",
  "passwordEnv": "CB_MASTER_PASSWORD",
  "passwordSource": "env",
  "passwordState": "default"
}

This output corresponds to the default settings.

Specifying a Custom Script for Obtaining the Master Pasword

The following call specifies, as the value of passwordCmd, a path to a custom script, and provides the script’s required arguments.

curl -v -X POST http://localhost:8091/node/controller/secretsManagement/encryptionService \
-u Administrator:password \
-H "Content-Type:application/json" -s -d "$(cat)" | jq
{
    "keyEncrypted": true,
    "passwordSource": "script",
    "passwordCmd": "/home/vagrant/pwdScript.sh param1 param2"
} // Exit with ^D

If successful, the call returns 200 OK and the following object, which confirms the new configuration.

{
  "keyEncrypted": true,
  "keyPath": "auto",
  "keyStorageType": "file",
  "passwordCmd": "/home/vagrant/pwdScript.sh param1 param2",
  "passwordSource": "script",
  "passwordState": "user_configured"
}

Specifying Custom Scripts for Handling data keys

The following call specifies custom scripts for the reading, writing, and deleting of data keys:

curl -v -X POST http://localhost:8091/node/controller/secretsManagement/encryptionService \
-u Administrator:password \
-H "Content-Type:application/json" -s -d "$(cat)" | jq
{
    "keyStorageType": "script",
    "readCmd": "/home/vagrant/readScript.sh",
    "writeCmd": "/home/vagrant/writeScript.sh",
    "deleteCmd": "/home/vagrant/deleteScript.sh"
} // Exit with ^D

If the command is successful, output of the following form confirms the change in configuration:

{
    "deleteCmd": "/home/vagrant/deleteScript.sh",
    "keyStorageType": "script",
    "passwordState": "password_not_used",
    "readCmd": "/home/vagrant/readScript.sh",
    "writeCmd": "/home/vagrant/writeScript.sh"
}

Re-Establishing the Default Configuration

The following call re-establishes the default configuration.

curl -v -X POST http://localhost:8091/node/controller/secretsManagement/encryptionService \
-u Administrator:password \
-H "Content-Type:application/json" -s -d "$(cat)" | jq
{
    "keyStorageType": "file",
    "keyEncrypted": true,
    "passwordSource": "env",
    "passwordEnv": "CB_MASTER_PASSWORD"
  } // Exit with ^D

If successful, the call returns 200 OK, and the following object, which confirms restoration of the default settings:

{
  "keyEncrypted": true,
  "keyPath": "auto",
  "keyStorageType": "file",
  "passwordEnv": "CB_MASTER_PASSWORD",
  "passwordSource": "env",
  "passwordState": "default"
}

Designing Scripts for Handling data keys

Requirements for the behavior of customer scripts for reading, writing, and deleting data keys are described below. Note that the master password is not used, when these commands are executed.

Scripts for Writing data keys

A custom script for writing data keys must accept at least one, and at most two arguments. The first (or only) argument is always the main key to be used. If a second argument is provided, this is the backup key, which is only used when the node rotates data keys. If two keys are specified, they should be separated by a space.

The following command would establish only the main key:

/home/vagrant/writeScript.sh BVegHS0+3jg/Ffn0inhJq6tuJRcOjnQNpBpyy6Cf45w=

The following command would establish both the main and the backup key:

/home/vagrant/writeScript.sh BVegHS0+3jg/Ffn0inhJq6tuJRcOjnQNpBpyy6Cf45w= \
UtCwS6mKnXJS1r76Rb6oDyITWi/XIuQia5/rcSiZvFY="

The script must exit with code 0.

Scripts for Reading Data Keys

A custom script for reading data keys must return between zero and two keys, as follows.

If the custom script that is the value of writeScript:

Has not yet been used, the script for reading exits with code 0, and returns no key. For example:
```
$ /home/vagrant/readScript.sh
$
```
Has written only one key (the main key), the script for reading exits with code 0, and returns the main key. For example:
```
$ /home/vagrant/readScript.sh
BVegHS0+3jg/Ffn0inhJq6tuJRcOjnQNpBpyy6Cf45w=
$
```

Has written two keys (the main and backup keys), the script for reading exits with code 0, and returns both keys. For example:

$ /home/vagrant/readScript.sh
BVegHS0+3jg/Ffn0inhJq6tuJRcOjnQNpBpyy6Cf45w= UtCwS6mKnXJS1r76Rb6oDyITWi/XIuQia5/rcSiZvFY="
$

Note that the encryption-key format is opaque, and can only be created by the instance of Couchbase Server running on the node.