diff --git a/website/source/api/system/rekey-recovery-key.html.md b/website/source/api/system/rekey-recovery-key.html.md index 360972ebc..12389d9a3 100644 --- a/website/source/api/system/rekey-recovery-key.html.md +++ b/website/source/api/system/rekey-recovery-key.html.md @@ -39,7 +39,8 @@ $ curl \ "progress": 1, "required": 3, "pgp_fingerprints": ["abcd1234"], - "backup": true + "backup": true, + "verification_required": false } ``` @@ -49,7 +50,8 @@ 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 @@ -81,6 +83,15 @@ nonce. `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. While this can be used with + `pgp_keys`, it also can be used without. + ### Sample Payload ```json @@ -104,7 +115,8 @@ $ curl \ 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. +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 | Produces | | :------- | :---------------------------------------- | :--------------------- | @@ -173,6 +185,14 @@ 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 | Produces | | :------- | :---------------------------------------- | :--------------------- | | `PUT` | `/sys/rekey-recovery-key/update` | `200 application/json` | @@ -187,8 +207,8 @@ call. ```json { - "key": "abcd1234...", - "nonce": "AB32..." + "key": "AB32...", + "nonce": "abcd1234..." } ``` @@ -211,10 +231,162 @@ $ curl \ "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", "pgp_fingerprints": ["abcd1234"], "keys_base64": ["base64keyvalue"], - "backup": true + "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 | Produces | +| :------- | :------------------------------------------ | :--------------------- | +| `GET` | `/sys/rekey-recovery-key/verify` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/sys/rekey/verify +``` + +### Sample Response + +```json +{ + "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. + +## Read Rekey Recovery Key Verification Progress + +This endpoint reads the configuration and progress of the current rekey +verification attempt. + +| Method | Path | Produces | +| :------- | :------------------------------------------ | :--------------------- | +| `GET` | `/sys/rekey-recovery-key/verify` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/sys/rekey-recovery-key/verify +``` + +### Sample Response + +```json +{ + "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 | Produces | +| :------- | :------------------------------------------ | :--------------------- | +| `DELETE` | `/sys/rekey-recovery-key/verify` | `200 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token" \ + --request DELETE \ + http://127.0.0.1:8200/v1/sys/rekey-recovery-key/verify +``` + +### Sample Response + +```json +{ + "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, +Vault 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 | Produces | +| :------- | :---------------------------------------- | :--------------------- | +| `PUT` | `/sys/rekey-recovery-key/verify` | `200 application/json` | + +### Parameters + +- `key` `(string: )` – Specifies a single recovery share key from the + new set of shares. + +- `nonce` `(string: )` – Specifies the nonce of the rekey + verification operation. + +### Sample Payload + +```json +{ + "key": "A58d...", + "nonce": "5a27bbc1..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token" \ + --request PUT \ + --data @payload.json \ + http://127.0.0.1:8200/v1/sys/rekey-recovery-key/verify +``` + +### Sample Response + +```json +{ + "nonce": "5827bbc1-0110-5725-cc21-beddc129d942", + "complete": true +} +``` diff --git a/website/source/api/system/rekey.html.md b/website/source/api/system/rekey.html.md index 39365d51c..70b3440b8 100644 --- a/website/source/api/system/rekey.html.md +++ b/website/source/api/system/rekey.html.md @@ -42,7 +42,8 @@ $ curl \ "progress": 1, "required": 3, "pgp_fingerprints": ["abcd1234"], - "backup": true + "backup": true, + "verification_required": false } ``` @@ -52,7 +53,8 @@ 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 @@ -83,6 +85,15 @@ and starting a new rekey, which will also provide a new nonce. `core/unseal-keys-backup` in the physical storage backend. These can then be retrieved and removed via the `sys/rekey/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 master + key is not actually rotated. The new keys must be provided to authorize the + actual rotation of the master 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. While this can be used with + `pgp_keys`, it also can be used without. + ### Sample Payload ```json @@ -106,7 +117,8 @@ $ curl \ 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. +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 | Produces | | :------- | :--------------------------- | :--------------------- | @@ -175,6 +187,14 @@ 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 | Produces | | :------- | :--------------------------- | :--------------------- | | `PUT` | `/sys/rekey/update` | `200 application/json` | @@ -189,8 +209,8 @@ call. ```json { - "key": "abcd1234...", - "nonce": "AB32..." + "key": "AB32...", + "nonce": "abcd1234..." } ``` @@ -213,10 +233,129 @@ $ curl \ "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", "pgp_fingerprints": ["abcd1234"], "keys_base64": ["base64keyvalue"], - "backup": true + "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 Verification Progress + +This endpoint reads the configuration and progress of the current rekey +verification attempt. + +| Method | Path | Produces | +| :------- | :----------------------------- | :--------------------- | +| `GET` | `/sys/rekey/verify` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/sys/rekey/verify +``` + +### Sample Response + +```json +{ + "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/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 | Produces | +| :------- | :----------------------------- | :--------------------- | +| `DELETE` | `/sys/rekey/verify` | `200 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token" \ + --request DELETE \ + http://127.0.0.1:8200/v1/sys/rekey/verify +``` + +### Sample Response + +```json +{ + "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, +Vault will complete the rekey by performing the actual rotation of the master +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/verify`, providing status on the operation itself. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/rekey/verify` | `200 application/json` | + +### Parameters + +- `key` `(string: )` – Specifies a single master share key from the + new set of shares. + +- `nonce` `(string: )` – Specifies the nonce of the rekey + verification operation. + +### Sample Payload + +```json +{ + "key": "A58d...", + "nonce": "5a27bbc1..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token" \ + --request PUT \ + --data @payload.json \ + http://127.0.0.1:8200/v1/sys/rekey/verify +``` + +### Sample Response + +```json +{ + "nonce": "5827bbc1-0110-5725-cc21-beddc129d942", + "complete": true +} +```