Document how to deal with regular passphrase rotation/rollover
Marco Ricci commited on 2026-04-05 21:50:47
Zeige 6 geänderte Dateien mit 24 Einfügungen und 2 Löschungen.
Once more, the quality is "first draft" level, but the main points are all present.
- docs/_future.md fdc46a2..ed744b5
- docs/how-tos/index.md be0d1d5..21e2e3f
- docs/how-tos/passphrase-rotation.md 0000000..70a21d2
- docs/tutorials/basic-setup-passphrase.md 8b40c8e..64e4c88
- mkdocs.yml a464d3a..0a733b3
- mkdocs_devsetup.yml 789a8d0..1ffa480
| ... | ... |
@@ -4,6 +4,8 @@ title: How-to overview |
| 4 | 4 |
|
| 5 | 5 |
* [How to setup `derivepassphrase vault` with an SSH key][SSH_KEY] |
| 6 | 6 |
* [How to deal with "supported" and "unsupported" special characters][SUPPORTED_SPECIAL_CHARACTERS] |
| 7 |
+* [How to deal with regular passphrase rotation/rollover][PASSPHRASE_ROTATION] |
|
| 7 | 8 |
|
| 8 | 9 |
[SSH_KEY]: ssh-key.md |
| 9 | 10 |
[SUPPORTED_SPECIAL_CHARACTERS]: supported-special-characters.md |
| 11 |
+[PASSPHRASE_ROTATION]: passphrase-rotation.md |
| ... | ... |
@@ -0,0 +1,18 @@ |
| 1 |
+# How to deal with regular passphrase rotation/rollover |
|
| 2 |
+ |
|
| 3 |
+`derivepassphrase vault` can only store one configuration per service name, and thus also generate only one passphrase per service name. |
|
| 4 |
+If a different passphrase is to be derived for a certain service *and* the previous derived passphrase(s) should remain accessible ("passphrase rotation"/"passphrase rollover"), we recommend using a set of *related service names* to designate the respective iterations of the service.
|
|
| 5 |
+ |
|
| 6 |
+We recommend different choices of related service names, depending on whether the passphrase rotation is *regular* or *irregular*: |
|
| 7 |
+ |
|
| 8 |
+ - For regular passphrase rotation, we recommend appending a suffix to the service name that indicates the "period" for this iteration of the service (including the period length). |
|
| 9 |
+ |
|
| 10 |
+ For example, for monthly iteration, the service name would then be suffixed with the year and month, zero-filled: `-2025-06`, `:2024/09`, `@202603`, etc. |
|
| 11 |
+ For yearly iteration, the suffix would just contain the year: `-2025`, `:2024`, `@2026`. |
|
| 12 |
+ |
|
| 13 |
+ For quarterly iteration, the suffix would also contain a `Q` to indicate quarterly rotation: `-2025Q2`, `:2024Q3`, `@2026Q1`, etc. |
|
| 14 |
+ (Weekly and fortnightly rotation work similarly, with indicators `W` and `WW`, respectively, and with zero-filling.) |
|
| 15 |
+ |
|
| 16 |
+ - For irregular passphrase rotation (e.g. after a password reset), we recommend using a counter: `@3`, `:5`, `c12`, etc. |
|
| 17 |
+ |
|
| 18 |
+These recommendations ensure that the set of related service names sorts *naturally*, i.e., that the *last* entry is the *latest* entry. |
| ... | ... |
@@ -263,7 +263,7 @@ So some part of the configuration---generally the service name---needs to change |
| 263 | 263 |
|
| 264 | 264 |
!!! abstract "Further reading" |
| 265 | 265 |
|
| 266 |
- → How to deal with regular passphrase rotation (TODO) |
|
| 266 |
+ → [How to deal with regular passphrase rotation/rollover][PASSPHRASE_ROTATION] |
|
| 267 | 267 |
|
| 268 | 268 |
We choose to append a very coarse timestamp to the "base" service name `work`: the 4-digit year, a `Q`, and the "quarter" number (1, 2, 3 or 4). |
| 269 | 269 |
As of October 2024, this leads to the final service name `work-2024Q4`. |
| ... | ... |
@@ -306,3 +306,4 @@ As a next step, you may want to [configure the accounts to use a master SSH key |
| 306 | 306 |
|
| 307 | 307 |
[BASIC_SETUP_SSH_KEY]: basic-setup-ssh-key.md "Tutorial: Using a master SSH key with derivepassphrase vault on existing accounts" |
| 308 | 308 |
[SUPPORTED_SPECIAL_CHARACTERS]: ../how-tos/supported-special-characters.md |
| 309 |
+[PASSPHRASE_ROTATION]: ../how-tos/passphrase-rotation.md |