Skip to main content

operator rotate-keys

info

The operator rotate-keys command is available from version v2.4.0.

The operator rotate-keys command generates a new set of unseal keys. This can optionally change the total number of key shares or the required threshold to reconstruct the root key. The rotation does not introduce downtime, but it requires the OpenBao instance to be unsealed and a quorum of existing unseal keys to be provided.

An unseal key may be provided directly on the command line as an argument to the command. If key is specified as "-", the command will read from stdin. If a TTY is available, the command will prompt for text.

Examples​

Initialize a rotation:

$ bao operator rotate-keys \
    -init \
    -key-shares=15 \
    -key-threshold=9

Initialize a rotation when Auto Unseal is used for the OpenBao cluster:

$ bao operator rotate-keys \
    -target=recovery \
    -init \
    -key-shares=15 \
    -key-threshold=9

Initialize a rotation and activate the verification process:

$ bao operator rotate-keys \
    -init \
    -key-shares=15 \
    -key-threshold=9 \
    -verify

Rotate and encrypt the resulting unseal keys with PGP:

$ bao operator rotate-keys \
    -init \
    -key-shares=3 \
    -key-threshold=2 \
    -pgp-keys="keybase:openbao,keybase:jefferai,keybase:sethvargo"

Rotate an Auto Unseal OpenBao and encrypt the resulting recovery keys with PGP:

$ bao operator rotate-keys \
    -target=recovery \
    -init \
    -key-shares=1 \
    -key-threshold=1 \
    -pgp-keys=keybase:grahamopenbao

Store encrypted PGP keys in OpenBao's core:

$ bao operator rotate-keys \
    -init \
    -pgp-keys="..." \
    -backup

Retrieve backed-up unseal keys:

$ bao operator rotate-keys -backup-retrieve

Delete backed-up unseal keys:

$ bao operator rotate-keys -backup-delete

Perform the verification of the rotation using the verification nonce:

$ bao operator rotate-keys -verify -nonce="..."

Usage​

The following flags are available in addition to the standard set of flags included on all commands.

Output options​

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the BAO_FORMAT environment variable.

Command options​

  • -cancel (bool: false) - Reset the rotation progress. This will discard any submitted unseal keys or configuration. The default is false.

  • -init (bool: false) - Initialize the rotation. This can only be done if there's not one in progress. Customize the new number of key shares and threshold using the -key-shares and -key-threshold flags respectively.

  • -key-shares (int: 5) - Number of key shares to split the generated root key into. This is the number of "unseal keys" to generate. This is aliased as -n

  • -key-threshold (int: 3) - Number of key shares required to reconstruct the root key. This must be less than or equal to -key-shares. This is aliased as -t.

  • -nonce (string: "") - Nonce value provided at initialization. The same nonce value must be provided with each unseal key.

  • -pgp-keys (string: "...") - Comma-separated list of paths to files on disk containing public PGP keys OR a comma-separated list of Keybase usernames using the format keybase:<username>. When supplied, the generated unseal keys will be encrypted and base64-encoded in the order specified in this list.

  • -status (bool: false) - Print the status of the current attempt without providing an unseal key. The default is false.

  • -target (string: "barrier") - Target for rotation. "recovery" only applies when HSM support is enabled or using Auto Unseal.

  • -verify (bool: false) - Indicate during the phase -init that the verification process is activated for the rotation. Along with -nonce option it indicates that the nonce given is for the verification process.

Backup options​

  • -backup (bool: false) - Store a backup of the current PGP encrypted unseal keys in OpenBao's core. The encrypted values can be recovered in the event of failure or discarded after success. See the -backup-delete and -backup-retrieve options for more information. This option only applies when the existing unseal keys were PGP encrypted.

  • -backup-delete (bool: false) - Delete any stored backup unseal keys.

  • -backup-retrieve (bool: false) - Retrieve the backed-up unseal keys. This option is only available if the PGP keys were provided and the backup has not been deleted.