open-vault/website/source/docs/http/sys-rekey.html.md

layout	page_title	sidebar_current	description
http	HTTP API: /sys/rekey/	docs-http-rotate-rekey	The `/sys/rekey/` endpoints are used to rekey the unseal keys for Vault.

/sys/rekey/init

GET

Description

Reads the configuration and progress of the current rekey attempt.

Method

GET

URL

`/sys/rekey/init`

Parameters

None

Returns

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

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

PUT

Description

Initializes a new rekey attempt. Only a single 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

PUT

URL

`/sys/rekey/init`

Parameters

• secret_shares required The number of shares to split the master key into.
• secret_threshold required The number of shares required to reconstruct the master key. This must be less than or equal to secret_shares.
• pgp_keys optional An array of PGP public keys used to encrypt the output unseal keys. 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 optional If using PGP-encrypted keys, whether Vault should also back them up to a well-known location in physical storage (`core/unseal-keys-backup`). These can then be retrieved and removed via the `sys/rekey/backup` endpoint.

Returns

`204` response code.

DELETE

Description

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.

Method

DELETE

URL

`/sys/rekey/init`

Parameters

None

Returns

`204` response code.

/sys/rekey/backup

GET

Description

Return the backup copy of PGP-encrypted unseal keys. The returned value is the nonce of the rekey operation and a map of PGP key fingerprint to hex-encoded PGP-encrypted key.

Method

GET

URL

`/sys/rekey/backup`

Parameters

None

Returns

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

DELETE

Description

Delete the backup copy of PGP-encrypted unseal keys.

Method

DELETE

URL

`/sys/rekey/backup`

Parameters

None

Returns

`204` response code.

/sys/rekey/update

PUT

Description

Enter a single master key share to progress the rekey of the Vault. If the threshold number of master key shares is reached, Vault 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.

Method

PUT

URL

`/sys/rekey/update`

Parameters

• key required A single master share key.
• nonce required The nonce of the rekey operation.

Returns

A JSON-encoded object indicating the rekey operation nonce and completion status; if completed, the new master keys are returned. 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:

```javascript
{
  "complete": true,
  "keys": ["one", "two", "three"],
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "pgp_fingerprints": ["abcd1234"],
  "backup": true
}
```