diff --git a/website/source/api/system/rekey-recovery-key.html.md b/website/source/api/system/rekey-recovery-key.html.md new file mode 100644 index 000000000..b85fbe0bb --- /dev/null +++ b/website/source/api/system/rekey-recovery-key.html.md @@ -0,0 +1,220 @@ +--- +layout: "api" +page_title: "/sys/rekey-recovery-key - HTTP API" +sidebar_current: "docs-http-system-rekey-recovery-key" +description: |- + The `/sys/rekey-recovery-key` endpoints are used to rekey the recovery keys for Vault. +--- + +# `/sys/rekey-recovery-key` + +~> **Note:** These endpoints are only applicable to seals that support recovery keys. + +The `/sys/rekey-recovery-key` endpoints are used to rekey the recovery keys for Vault. + +## Read Rekey Progress + +This endpoint reads the configuration and progress of the current rekey attempt. + +| Method | Path | Produces | +| :------- | :---------------------------------------- | :--------------------- | +| `GET` | `/sys/rekey-recovery-key/init` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/rekey-recovery-key/init +``` + +### Sample Response + +```json +{ + "started": true, + "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", + "t": 3, + "n": 5, + "progress": 1, + "required": 3, + "pgp_fingerprints": ["abcd1234"], + "backup": true +} +``` + +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. + + +## 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 | Produces | +| :------- | :---------------------------------------- | :--------------------- | +| `PUT` | `/sys/rekey-recovery-key/init` | `204 (empty body)` | + +### Parameters + +- `secret_shares` `(int: )` – Specifies the number of shares to split + the recovery key into. + +- `secret_threshold` `(int: )` – Specifies the number of shares + required to reconstruct the recovery key. This must be less than or equal to + `secret_shares`. + +- `pgp_keys` `(array: 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 + Vault 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. + +### Sample Payload + +```json +{ + "secret_shares": 10, + "secret_threshold": 5 +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/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. + +| Method | Path | Produces | +| :------- | :---------------------------------------- | :--------------------- | +| `DELETE` | `/sys/rekey-recovery-key/init` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/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 | Produces | +| :------- | :---------------------------------------- | :--------------------- | +| `GET` | `/sys/rekey-recovery-key/backup` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/rekey-recovery-key/backup +``` + +### Sample Response + +```json +{ + "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 | Produces | +| :------- | :---------------------------------------- | :--------------------- | +| `DELETE` | `/sys/rekey-recovery-key/backup` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token" \ + --request DELETE \ + https://vault.rocks/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 Vault. If the threshold number of recovery 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 | Path | Produces | +| :------- | :---------------------------------------- | :--------------------- | +| `PUT` | `/sys/rekey-recovery-key/update` | `200 application/json` | + +### Parameters + +- `key` `(string: )` – Specifies a single recovery share key. + +- `nonce` `(string: )` – Specifies the nonce of the rekey operation. + +### Sample Payload + +```json +{ + "key": "abcd1234...", + "nonce": "AB32..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token" \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/rekey-recovery-key/update +``` + +### Sample Response + +```json +{ + "complete": true, + "keys": ["one", "two", "three"], + "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", + "pgp_fingerprints": ["abcd1234"], + "keys_base64": ["base64keyvalue"], + "backup": true +} +``` + +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. diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index 33db45308..d43efe7a5 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -217,6 +217,9 @@ > /sys/rekey + > + /sys/rekey-recovery-key + > /sys/remount