Skip to content

Commit e9e0176

Browse files
BrocksiNetchr-hertel
authored andcommitted
[Docs] Add the preparation phase to the requestState key rotation
A rolling deployment that moves straight to `[$new, $old]` signs states its peers still on `[$old]` refuse. The builder docblock now names the `[$current, $new]` step, and the retirement TTL starts when the last instance stops signing with the old key.
1 parent 5eb4e84 commit e9e0176

2 files changed

Lines changed: 7 additions & 3 deletions

File tree

‎docs/handlers/input-required.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,8 @@ To rotate without failing the calls in flight:
114114
A single-process deployment can skip this step.
115115
2. Move the new key to the front, `[$new, $current]`. States are signed with the new key from
116116
now on, and the ones the old key signed still verify.
117-
3. After one TTL, every state the old key signed has expired. Remove it, `[$new]`.
117+
3. Wait one TTL after the **last** process switched to `[$new, $current]`: only then has every
118+
state the old key signed expired. Remove it, `[$new]`.
118119

119120
Each key needs at least 32 bytes.
120121

‎src/Server/Builder.php‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -378,8 +378,11 @@ public function setCachePolicy(CachePolicy $policy): self
378378
* per-process random value only works for a single-process deployment.
379379
*
380380
* A list of keys is a key ring: the first key signs, every key verifies.
381-
* To rotate, put the new key first and keep the old one behind it until
382-
* the states it signed have expired, one TTL later.
381+
* To rotate across several instances, first add the new key behind the
382+
* current one everywhere, `[$current, $new]`, so every instance accepts it
383+
* before any signs with it. Then move it to the front, `[$new, $current]`,
384+
* and remove the old key one TTL after the last instance stopped signing
385+
* with it. See docs/handlers/input-required.md, "Rotating the key".
383386
*
384387
* @param string|list<string> $key the signing key or key ring, each key at least 32 bytes
385388
* @param int $ttl how long a minted state stays valid, in seconds

0 commit comments

Comments
 (0)