A newer version of this documentation is available.

View Latest

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.
Secret Management is an Enterprise Edition only feature.

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.

secret mgmt

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.

This is primarily a production feature for hardening Couchbase Server security. If you do not wish to make use of this feature then you do not have to set a master password.

Password Rotation

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

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.

The above step must be repeated for every Couchbase Server node in the cluster. The secret management couchbase-cli commands must be run on the same node that the server is on.

To indicate Couchbase Server to decrypt secrets, follow one of the following options:

Set the environment variable to indicate Couchbase Server to read the password from the environment variable.

If Couchbase Server is started as a service, make sure the environment variable is available to the service, otherwise, if Couchbase Server is started as a script, then use the export command.

For example, on Ubuntu, use the bash shell terminal to run the following command:

export CB_MASTER_PASSWORD='P@$$wor4'

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.

If you’re a developer and wants to try out secret management on Mac OS X, there are extra considerations to bear in mind:

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.

To set the master password using the prompt:

  1. 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.

  2. Run the following command to manually enter the password for a server:

    couchbase-cli master-password -c <server-ip>:8091 --send-password

This script allows you three attempts to correctly enter the password.

By default, Couchbase Server reads the environment variable to decrypt secrets on startup. If you are starting Couchbase Server using a script, after setting the environment variable for a password prompt using command line you must restart Couchbase Server, and in another prompt manually enter the password using the CLI command.

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.