1--- 2layout: "api" 3page_title: "/sys/rekey - HTTP API" 4sidebar_title: "<code>/sys/rekey</code>" 5sidebar_current: "api-http-system-rekey" 6description: |- 7 The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault. 8--- 9 10# `/sys/rekey` 11 12The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault. 13 14On seals that support stored keys (e.g. HSM PKCS11), the recovery key share(s) 15can be provided to rekey the master key since no unseal keys are available. The 16secret shares, secret threshold, and stored shares parameters must be set to 1. 17Upon successful rekey, no split unseal key shares are returned. 18 19## Read Rekey Progress 20 21This endpoint reads the configuration and progress of the current rekey attempt. 22 23| Method | Path | 24| :--------------------------- | :--------------------- | 25| `GET` | `/sys/rekey/init` | 26 27### Sample Request 28 29``` 30$ curl \ 31 --header "X-Vault-Token: ..." \ 32 http://127.0.0.1:8200/v1/sys/rekey/init 33``` 34 35### Sample Response 36 37```json 38{ 39 "started": true, 40 "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", 41 "t": 3, 42 "n": 5, 43 "progress": 1, 44 "required": 3, 45 "pgp_fingerprints": ["abcd1234"], 46 "backup": true, 47 "verification_required": false 48} 49``` 50 51If a rekey is started, then `n` is the new shares to generate and `t` is the 52threshold required for the new shares. `progress` is how many unseal keys have 53been provided for this rekey, where `required` must be reached to complete. The 54`nonce` for the current rekey operation is also displayed. If PGP keys are being 55used to encrypt the final shares, the key fingerprints and whether the final 56keys will be backed up to physical storage will also be displayed. 57`verification_required` indicates whether verification was enabled for this 58operation. 59 60## Start Rekey 61 62This endpoint initializes a new rekey attempt. Only a single rekey attempt can 63take place at a time, and changing the parameters of a rekey requires canceling 64and starting a new rekey, which will also provide a new nonce. 65 66| Method | Path | 67| :--------------------------- | :--------------------- | 68| `PUT` | `/sys/rekey/init` | 69 70### Parameters 71 72- `secret_shares` `(int: <required>)` – Specifies the number of shares to split 73 the master key into. 74 75- `secret_threshold` `(int: <required>)` – Specifies the number of shares 76 required to reconstruct the master key. This must be less than or equal to 77 `secret_shares`. 78 79- `pgp_keys` `(array<string>: nil)` – Specifies an array of PGP public keys used 80 to encrypt the output unseal keys. Ordering is preserved. The keys must be 81 base64-encoded from their original binary representation. The size of this 82 array must be the same as `secret_shares`. 83 84- `backup` `(bool: false)` – Specifies if using PGP-encrypted keys, whether 85 Vault should also store a plaintext backup of the PGP-encrypted keys at 86 `core/unseal-keys-backup` in the physical storage backend. These can then 87 be retrieved and removed via the `sys/rekey/backup` endpoint. 88 89- `require_verification` `(bool: false)` – This turns on verification 90 functionality. When verification is turned on, after successful authorization 91 with the current unseal keys, the new unseal keys are returned but the master 92 key is not actually rotated. The new keys must be provided to authorize the 93 actual rotation of the master key. This ensures that the new keys have been 94 successfully saved and protects against a risk of the keys being lost after 95 rotation but before they can be persisted. This can be used with without 96 `pgp_keys`, and when used with it, it allows ensuring that the returned keys 97 can be successfully decrypted before committing to the new shares, which the 98 backup functionality does not provide. 99 100### Sample Payload 101 102```json 103{ 104 "secret_shares": 10, 105 "secret_threshold": 5 106} 107``` 108 109### Sample Request 110 111``` 112$ curl \ 113 --header "X-Vault-Token: ..." \ 114 --request PUT \ 115 --data @payload.json \ 116 http://127.0.0.1:8200/v1/sys/rekey/init 117``` 118 119## Cancel Rekey 120 121This endpoint cancels any in-progress rekey. This clears the rekey settings as 122well as any progress made. This must be called to change the parameters of the 123rekey. Note: verification is still a part of a rekey. If rekeying is canceled 124during the verification flow, the current unseal keys remain valid. 125 126| Method | Path | 127| :--------------------------- | :--------------------- | 128| `DELETE` | `/sys/rekey/init` | 129 130### Sample Request 131 132``` 133$ curl \ 134 --header "X-Vault-Token: ..." \ 135 --request DELETE \ 136 http://127.0.0.1:8200/v1/sys/rekey/init 137``` 138 139## Read Backup Key 140 141This endpoint returns the backup copy of PGP-encrypted unseal keys. The returned 142value is the nonce of the rekey operation and a map of PGP key fingerprint to 143hex-encoded PGP-encrypted key. 144 145| Method | Path | 146| :--------------------------- | :--------------------- | 147| `GET` | `/sys/rekey/backup` | 148 149### Sample Request 150 151``` 152$ curl \ 153 --header "X-Vault-Token: ..." \ 154 http://127.0.0.1:8200/v1/sys/rekey/backup 155``` 156 157### Sample Response 158 159```json 160{ 161 "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", 162 "keys": { 163 "abcd1234": "..." 164 } 165} 166``` 167 168## Delete Backup Key 169 170This endpoint deletes the backup copy of PGP-encrypted unseal keys. 171 172| Method | Path | 173| :--------------------------- | :--------------------- | 174| `DELETE` | `/sys/rekey/backup` | 175 176### Sample Request 177 178``` 179$ curl \ 180 --header "X-Vault-Token" \ 181 --request DELETE \ 182 http://127.0.0.1:8200/v1/sys/rekey/backup 183``` 184 185## Submit Key 186 187This endpoint is used to enter a single master key share to progress the rekey 188of the Vault. If the threshold number of master key shares is reached, Vault 189will complete the rekey. Otherwise, this API must be called multiple times until 190that threshold is met. The rekey nonce operation must be provided with each 191call. 192 193When the operation is complete, this will return a response like the example 194below; otherwise the response will be the same as the `GET` method against 195`sys/rekey/init`, providing status on the operation itself. 196 197If verification was requested, successfully completing this flow will 198immediately put the operation into a verification state, and provide the nonce 199for the verification operation. 200 201| Method | Path | 202| :--------------------------- | :--------------------- | 203| `PUT` | `/sys/rekey/update` | 204 205### Parameters 206 207- `key` `(string: <required>)` – Specifies a single master share key. 208 209- `nonce` `(string: <required>)` – Specifies the nonce of the rekey operation. 210 211### Sample Payload 212 213```json 214{ 215 "key": "AB32...", 216 "nonce": "abcd1234..." 217} 218``` 219 220### Sample Request 221 222``` 223$ curl \ 224 --header "X-Vault-Token" \ 225 --request PUT \ 226 --data @payload.json \ 227 http://127.0.0.1:8200/v1/sys/rekey/update 228``` 229 230### Sample Response 231 232```json 233{ 234 "complete": true, 235 "keys": ["one", "two", "three"], 236 "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", 237 "pgp_fingerprints": ["abcd1234"], 238 "keys_base64": ["base64keyvalue"], 239 "backup": true, 240 "verification_required": true, 241 "verification_nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10" 242} 243``` 244 245If the keys are PGP-encrypted, an array of key fingerprints will also be 246provided (with the order in which the keys were used for encryption) along with 247whether or not the keys were backed up to physical storage. 248 249## Read Rekey Verification Progress 250 251This endpoint reads the configuration and progress of the current rekey 252verification attempt. 253 254| Method | Path | 255| :----------------------------- | :--------------------- | 256| `GET` | `/sys/rekey/verify` | 257 258### Sample Request 259 260``` 261$ curl \ 262 --header "X-Vault-Token: ..." \ 263 http://127.0.0.1:8200/v1/sys/rekey/verify 264``` 265 266### Sample Response 267 268```json 269{ 270 "nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10", 271 "t": 3, 272 "n": 5, 273 "progress": 1 274} 275``` 276 277`n` is the total number of new shares that were generated and `t` is the 278threshold required for the new shares to pass verification. `progress` is how 279many of the new unseal keys have been provided for this verification operation. 280The `nonce` for the current rekey operation is also displayed. 281 282## Cancel Rekey Verification 283 284This endpoint cancels any in-progress rekey verification operation. This clears 285any progress made and resets the nonce. Unlike a `DELETE` against 286`sys/rekey/init`, this only resets the current verification operation, not the 287entire rekey atttempt. The return value is the same as `GET` along with the new 288nonce. 289 290| Method | Path | 291| :----------------------------- | :--------------------- | 292| `DELETE` | `/sys/rekey/verify` | `200 (empty body)` | 293 294### Sample Request 295 296``` 297$ curl \ 298 --header "X-Vault-Token" \ 299 --request DELETE \ 300 http://127.0.0.1:8200/v1/sys/rekey/verify 301``` 302 303### Sample Response 304 305```json 306{ 307 "nonce": "5827bbc1-0110-5725-cc21-beddc129d942", 308 "t": 3, 309 "n": 5, 310 "progress": 0 311} 312``` 313 314## Submit Verification Key 315 316This endpoint is used to enter a single new key share to progress the rekey 317verification operation. If the threshold number of new key shares is reached, 318Vault will complete the rekey by performing the actual rotation of the master 319key. Otherwise, this API must be called multiple times until that threshold is 320met. The nonce must be provided with each call. 321 322When the operation is complete, this will return a response like the example 323below; otherwise the response will be the same as the `GET` method against 324`sys/rekey/verify`, providing status on the operation itself. 325 326| Method | Path | 327| :--------------------------- | :--------------------- | 328| `PUT` | `/sys/rekey/verify` | 329 330### Parameters 331 332- `key` `(string: <required>)` – Specifies a single master share key from the 333 new set of shares. 334 335- `nonce` `(string: <required>)` – Specifies the nonce of the rekey 336 verification operation. 337 338### Sample Payload 339 340```json 341{ 342 "key": "A58d...", 343 "nonce": "5a27bbc1..." 344} 345``` 346 347### Sample Request 348 349``` 350$ curl \ 351 --header "X-Vault-Token" \ 352 --request PUT \ 353 --data @payload.json \ 354 http://127.0.0.1:8200/v1/sys/rekey/verify 355``` 356 357### Sample Response 358 359```json 360{ 361 "nonce": "5827bbc1-0110-5725-cc21-beddc129d942", 362 "complete": true 363} 364``` 365