Add verification documentation
This commit is contained in:
Jeff Mitchell
parent
c55a2ec486
commit
27ab8d1a20
|
|
@ -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: <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
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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: <required>)` – Specifies a single master share key from the
|
||||
new set of shares.
|
||||
|
||||
- `nonce` `(string: <required>)` – 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
|
||||
}
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue