Manage System Secrets
System secrets can be managed with a special degree of security.
Understanding System Secrets
Secret-Management (which is an Enterprise Edition feature of Couchbase Server) allows system secrets to be written to disk in encrypted format. Secrets are Couchbase Server-defined, and include system-essential passwords and certificates. Couchbase uses an AES 256-bit algorithm in GCM mode, to encrypt secrets using an encryption hierarchy.
Setting the Master Password
Secret-Management is an optional feature that only works when the master password is set for each Couchbase Server node.
This can be specified by means of the cli:cbcli/couchbase-cli-master-password.adoc CLI command; the REST API POST /node/controller/changeMasterPassword method; and (on all supported operating systems other than Mac OS X) by explicitly setting the CB_MASTER_PASSWORD
environment variable, at the command-prompt.
Note that since the CB_MASTER_PASSWORD
does not work with Couchbase Server on Mac OS X, Mac developers should open the /Applications/Couchbase Server.app/Contents/Resources/start-server.sh
script, and add the export variable to that file.
When you specify the master password, Couchbase Server derives a master key from that password, using the strong Key Derivation Function PBKDF2. Couchbase Server also creates a random data key, which is then encrypted with the master key. The data key will be used to encrypt all secrets on disk, using an AES 256-bit algorithm, in GCM mode. To bootstrap the system, the master key is used to open the encrypted data key; the data key is then used to open the encrypted secrets; and the secrets are then used to start Couchbase Server.
If you establish the master password by setting the environment variable for the current node while Couchbase Server is running, Couchbase Server performs encryption on secrets from that point.
However, by default, the decryption of secrets relies on Couchbase Server having read the environment variable on startup.
Therefore, if Couchbase Server has already been started as a service at the time you set the environment variable, you must explicitly make the newly established variable available to the service.
If Couchbase Server has already been started as a script, you must use the export
command, to make it available to the script.
From Couchbase Server 4.6.2 onwards, on initial start-up, Couchbase Server waits by default for the master password to be entered at the prompt.
Enter the password by means of the CLI command with the --send-password
option:
couchbase-cli master-password -c server-ip-address:8091 --send-password
This CLI command allows you three attempts to enter the password correctly.
Note that Couchbase Server 4.6.0 and 4.6.1 do not wait by default for the master password to be entered. To make them do so, set the following, additional environment variable:
export CB_WAIT_FOR_MASTER_PASSWORD=true
Performing Rotation
The Couchbase Server Secret-Management system allows you to rotate (periodically change, to reduce the risk of illicit discovery or deciphering) the different elements of the system:
-
Master-password rotation: This first level of rotation is achieved by setting a new password, using the cli:cbcli/couchbase-cli-master-password.adoc, the REST API method, or (other than on Mac OS X) the environment variable, as indicated above. One master password per node needs to be set.
-
Data-key rotation: This second level of rotation is achieved by changing the data-key, using the cli:cbcli/couchbase-cli-master-password.adoc with the
--rotate-data-key
option, or the REST API POST /node/controller/rotateDataKey method. -
Secret rotation: This third level of rotation is achieved by changing the values of the secrets themselves. For example, to reset the secret that is an administrator password, use the cli:cbcli/couchbase-cli-reset-admin-password.adoc command.
Note that if the auditing option is enabled, all rotation-requests are audited by Couchbase Server.