Secret Management and Hardening
Using the Secret Management functionality, Couchbase Server provides a way to securely manage server secrets, which helps hardening of Couchbase Server. This feature allows businesses to fulfill important requirements around their server secrets (such as passwords) needed for compliance.
A secret is something you don't want anyone to know, for Couchbase Server these are entities such as administrator and bucket passwords. Secrets must be stored in a secure way and access to these secrets must be controlled to reduce the risk of accidental exposure. With secret management in Couchbase Server, secrets are written to disk in encrypted format. Couchbase uses an AES 256-bit algorithm in GCM mode to encrypt secrets using an encryption hierarchy as shown in the following illustration.
To make use of this feature, set the master password for each Couchbase Server node. The master password is at the top of the encryption hierarchy. The master password is either user specified or inserted into the system using a system environment variable CB_MASTER_PASSWORD. If the environment variable is not set, Couchbase Server waits until the master password is specified using the prompt. Couchbase recommends that you use a strong master password.
When you specify a master password, Couchbase Server derives a master key from that password. This zero-knowledge password design hardens the Couchbase Server system.
To bootstrap the system, the master key is used to open the encrypted data key. The decrypted data key is then used to open the encrypted secrets, and the secrets are used to start Couchbase Server.
With Secret Management, you can rotate your secrets at different levels of the key hierarchy periodically or in the event of a breach.
- Master password rotation - This first level of rotation can be achieved by setting a new password using the CLI or REST API. Couchbase Server allows the flexibility of setting one master password per node.
- Data key rotation - This second level of rotation can be done by changing the data key using the CLI or REST API.
- Secret rotation - This third level of rotation can be done by changing the values of the secrets. For example, to reset the administrator password secrets use the couchbase-cli reset-admin-password command.
For better security, you can rotate your password anytime without any application downtime, and all rotation requests are audited by Couchbase Server if the auditing option is enabled.
Configuring the Master Password
You can set the master password by using the environment variable or during the initial startup using the prompt.
To indicate Couchbase Server to encrypt secrets using the new master password, use the REST API or CLI command, for example, run the following CLI command:
couchbase-cli master-password –c <server-ip>:8091 –u Administrator –p password —-new-password
At this point, you’ll be asked to enter a new master password to encrypt your node's secrets. For example, you can specify a strong password such as P@$$wor4.
To indicate Couchbase Server to decrypt secrets, follow one of the following options:
For example, on Ubuntu, use the bash shell terminal to run the following command:
Here, P@$$wor4 has been enclosed in single quotes, to ensure that all special characters are interpreted strictly as plain characters. Equivalent precautions should be taken on other operating systems.
On Mac OS X version, exporting the CB_MASTER_PASSWORD environment variable will not work with Couchbase Server. Instead, open the /Applications/Couchbase Server.app/Contents/Resources/start-server.sh script and add the export variable command to that file.
- Couchbase Server 4.6.0 and 4.6.1 require an environment variable to be set to tell Couchbase Server to wait for the master password to be submitted via prompt:
From Couchbase Server 4.6.2 onwards, Couchbase Server waits for the master password to be entered by default. This means that you do not need to manually set the CB_WAIT_FOR_MASTER_PASSWORD environment variable.
- Run the following command to manually enter the password for a server:
couchbase-cli master-password -c <server-ip>:8091 --send-password
To rotate your server secrets using the CLI command, see master-password for details.
To rotate your server secrets using the REST API, see Secret Management API for details.