`/sys/rekey-recovery-key`

The /sys/rekey-recovery-key endpoints are used to rekey the recovery keys for OpenBao. Rekey endpoints only apply to seals that support recovery keys.

Read rekey progress

This endpoint reads the configuration and progress of the current rekey attempt.

Method	Path
`GET`	`/sys/rekey-recovery-key/init`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/rekey-recovery-key/init

Sample response

{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "t": 3,
  "n": 5,
  "progress": 1,
  "required": 3,
  "pgp_fingerprints": ["abcd1234"],
  "backup": true,
  "verification_required": false
}

If a rekey is started, then n is the new shares to generate and t is the threshold required for the new shares. progress is how many recovery keys have been provided for this rekey, where required must be reached to complete. The nonce for the current rekey operation is also displayed. If PGP keys are being used to encrypt the final shares, the key fingerprints and whether the final keys will be backed up to physical storage will also be displayed. verification_required indicates whether verification was enabled for this operation.

Start rekey

This endpoint initializes a new rekey attempt. Only a single recovery key rekey attempt can take place at a time, and changing the parameters of a rekey requires canceling and starting a new rekey, which will also provide a new nonce.

Method	Path
`POST`	`/sys/rekey-recovery-key/init`

Parameters

secret_shares (int: <required>) – Specifies the number of shares to split the recovery key into.
secret_threshold (int: <required>) – Specifies the number of shares required to reconstruct the recovery key. This must be less than or equal to secret_shares.
pgp_keys (array<string>: nil) – Specifies an array of PGP public keys used to encrypt the output recovery key shares. Ordering is preserved. The keys must be base64-encoded from their original binary representation. The size of this array must be the same as secret_shares.
backup (bool: false) – Specifies if using PGP-encrypted keys, whether OpenBao should also store a plaintext backup of the PGP-encrypted keys at core/recovery-keys-backup in the physical storage backend. These can then be retrieved and removed via the sys/rekey-recovery-key/backup endpoint.
require_verification (bool: false) – This turns on verification functionality. When verification is turned on, after successful authorization with the current unseal keys, the new unseal keys are returned but the recovery key is not actually rotated. The new keys must be provided to authorize the actual rotation of the key. This ensures that the new keys have been successfully saved and protects against a risk of the keys being lost after rotation but before they can be persisted. This can be used with without pgp_keys, and when used with it, it allows ensuring that the returned keys can be successfully decrypted before committing to the new shares, which the backup functionality does not provide.

Sample payload

{
  "secret_shares": 10,
  "secret_threshold": 5
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/rekey-recovery-key/init

Cancel rekey

This endpoint cancels any in-progress rekey. This clears the rekey settings as well as any progress made. This must be called to change the parameters of the rekey. Note: verification is still a part of a rekey. If rekeying is canceled during the verification flow, the current unseal keys remain valid.

Method	Path
`DELETE`	`/sys/rekey-recovery-key/init`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/rekey-recovery-key/init

Read backup key

This endpoint returns the backup copy of PGP-encrypted recovery key shares. The returned value is the nonce of the rekey operation and a map of PGP key fingerprint to hex-encoded PGP-encrypted key.

Method	Path
`GET`	`/sys/rekey/recovery-key-backup`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/rekey/recovery-key-backup

Sample response

{
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "keys": {
    "abcd1234": "..."
  }
}

Delete backup key

This endpoint deletes the backup copy of PGP-encrypted recovery key shares.

Method	Path
`DELETE`	`/sys/rekey/recovery-key-backup`

Sample request

$ curl \
    --header "X-Vault-Token" \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/rekey/recovery-key-backup

Submit key

This endpoint is used to enter a single recovery key share to progress the rekey of the OpenBao. If the threshold number of recovery key shares is reached, OpenBao will complete the rekey. Otherwise, this API must be called multiple times until that threshold is met. The rekey nonce operation must be provided with each call.

When the operation is complete, this will return a response like the example below; otherwise the response will be the same as the GET method against sys/rekey/init, providing status on the operation itself.

If verification was requested, successfully completing this flow will immediately put the operation into a verification state, and provide the nonce for the verification operation.

Method	Path
`POST`	`/sys/rekey-recovery-key/update`

Parameters

key (string: <required>) – Specifies a single recovery share key.
nonce (string: <required>) – Specifies the nonce of the rekey operation.

Sample payload

{
  "key": "AB32...",
  "nonce": "abcd1234..."
}

Sample request

$ curl \
    --header "X-Vault-Token" \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/rekey-recovery-key/update

Sample response

{
  "complete": true,
  "keys": ["one", "two", "three"],
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "pgp_fingerprints": ["abcd1234"],
  "keys_base64": ["base64keyvalue"],
  "backup": true,
  "verification_required": true,
  "verification_nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10"
}

If the keys are PGP-encrypted, an array of key fingerprints will also be provided (with the order in which the keys were used for encryption) along with whether or not the keys were backed up to physical storage.

Read rekey recovery key verification progress

This endpoint reads the configuration and progress of the current rekey verification attempt.

Method	Path
`GET`	`/sys/rekey-recovery-key/verify`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/rekey-recovery-key/verify

Sample response

{
  "nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10",
  "t": 3,
  "n": 5,
  "progress": 1
}

n is the total number of new shares that were generated and t is the threshold required for the new shares to pass verification. progress is how many of the new unseal keys have been provided for this verification operation. The nonce for the current rekey operation is also displayed.

Cancel rekey verification

This endpoint cancels any in-progress rekey verification operation. This clears any progress made and resets the nonce. Unlike a DELETE against sys/rekey-recovery-key/init, this only resets the current verification operation, not the entire rekey atttempt. The return value is the same as GET along with the new nonce.

Method	Path
`DELETE`	`/sys/rekey-recovery-key/verify`

Sample request

$ curl \
    --header "X-Vault-Token" \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/rekey-recovery-key/verify

Sample response

{
  "nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
  "t": 3,
  "n": 5,
  "progress": 0
}

Submit verification key

This endpoint is used to enter a single new key share to progress the rekey verification operation. If the threshold number of new key shares is reached, OpenBao will complete the rekey by performing the actual rotation of the recovery key. Otherwise, this API must be called multiple times until that threshold is met. The nonce must be provided with each call.

When the operation is complete, this will return a response like the example below; otherwise the response will be the same as the GET method against sys/rekey-recovery-key/verify, providing status on the operation itself.

Method	Path
`POST`	`/sys/rekey-recovery-key/verify`

Parameters

key (string: <required>) – Specifies a single recovery share key from the new set of shares.
nonce (string: <required>) – Specifies the nonce of the rekey verification operation.

Sample payload

{
  "key": "A58d...",
  "nonce": "5a27bbc1..."
}

Sample request

$ curl \
    --header "X-Vault-Token" \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/rekey-recovery-key/verify

Sample response

{
  "nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
  "complete": true
}

Read rekey progress​

Sample request​

Sample response​

Start rekey​

Parameters​

Sample payload​

Sample request​

Cancel rekey​

Sample request​

Read backup key​

Sample request​

Sample response​

Delete backup key​

Sample request​

Submit key​

Parameters​

Sample payload​

Sample request​

Sample response​

Read rekey recovery key verification progress​

Sample request​

Sample response​

Cancel rekey verification​

Sample request​

Sample response​

Submit verification key​

Parameters​

Sample payload​

Sample request​

Sample response​

Read rekey progress

Sample request

Sample response

Start rekey

Parameters

Sample payload

Sample request

Cancel rekey

Sample request

Read backup key

Sample request

Sample response

Delete backup key

Sample request

Submit key

Parameters

Sample payload

Sample request

Sample response

Read rekey recovery key verification progress

Sample request

Sample response

Cancel rekey verification

Sample request

Sample response

Submit verification key

Parameters

Sample payload

Sample request

Sample response