Document how to deal with "unsupported" special characters in derivepassphrase vault
Marco Ricci commited on 2026-04-05 21:02:18
Zeige 6 geänderte Dateien mit 54 Einfügungen und 3 Löschungen.
Again, somewhat more of a first sketch than finished documentation, but the main points are present.
- docs/_future.md fc7dbcf..fdc46a2
- docs/how-tos/index.md 1db23ff..be0d1d5
- docs/how-tos/supported-special-characters.md 0000000..2d9f948
- docs/tutorials/basic-setup-passphrase.md ef3d341..8b40c8e
- mkdocs.yml 8c3404a..a464d3a
- mkdocs_devsetup.yml 731f045..789a8d0
| ... | ... |
@@ -49,7 +49,6 @@ |
| 49 | 49 |
### How-tos |
| 50 | 50 |
|
| 51 | 51 |
* How to choose a good service name |
| 52 |
-* How to deal with "supported" and "unsupported" special characters (→ [TODO][BASIC_SETUP_PASSPHRASE]) |
|
| 53 | 52 |
* How to deal with regular passphrase rotation/rollover (→ [TODO][BASIC_SETUP_PASSPHRASE]) |
| 54 | 53 |
|
| 55 | 54 |
### Reference |
| ... | ... |
@@ -61,5 +60,4 @@ |
| 61 | 60 |
* Why is `vault`'s `--repeat` option named this way if it counts occurrences, not repetitions? |
| 62 | 61 |
|
| 63 | 62 |
[BASIC_SETUP_PASSPHRASE]: tutorials/basic-setup-passphrase.md |
| 64 |
-[BASIC_SETUP_SSH_KEY]: tutorials/basic-setup-ssh-key.md |
|
| 65 | 63 |
[HOW_TO_SSH_KEY]: how-tos/ssh-key.md |
| ... | ... |
@@ -3,5 +3,7 @@ title: How-to overview |
| 3 | 3 |
--- |
| 4 | 4 |
|
| 5 | 5 |
* [How to setup `derivepassphrase vault` with an SSH key][SSH_KEY] |
| 6 |
+* [How to deal with "supported" and "unsupported" special characters][SUPPORTED_SPECIAL_CHARACTERS] |
|
| 6 | 7 |
|
| 7 | 8 |
[SSH_KEY]: ssh-key.md |
| 9 |
+[SUPPORTED_SPECIAL_CHARACTERS]: supported-special-characters.md |
| ... | ... |
@@ -0,0 +1,48 @@ |
| 1 |
+# How to deal with "supported" and "unsupported" special characters |
|
| 2 |
+ |
|
| 3 |
+Some services/websites impose a required minimum amount of "special characters" in their passphrases. |
|
| 4 |
+`derivepassphrase vault` considers the following characters as special characters: `!"#$%&'()*+,./:;<=>?@[\]^{|}~-_`.
|
|
| 5 |
+However, in general, not every service/website will support this full range of special characters. |
|
| 6 |
+Worse, the service/website may not explicitly list the range of special characters it supports. |
|
| 7 |
+ |
|
| 8 |
+`derivepassphrase vault` supports restricting its range of special characters to `-_` via the `--dash` command-line option. |
|
| 9 |
+Beyond this, `derivepassphrase vault` does not support arbitrarily restricting its range of special characters -- you cannot directly tell `derivepassphrase` that a certain special character is "supported" or not. |
|
| 10 |
+Therefore, generating a passphrase acceptable to the service/website must be done indirectly, by finding a workable configuration. |
|
| 11 |
+ |
|
| 12 |
+Typically, a base configuration is "mutated" by changing the passphrase length, or requiring more or less fixed characters, until a workable configuration is found. |
|
| 13 |
+ |
|
| 14 |
+## Example |
|
| 15 |
+ |
|
| 16 |
+The work account from the [tutorial "Setting up `derivepassphrase vault` for three accounts, with a master passphrase"][BASIC_SETUP_PASSPHRASE] has the following stipulations: exactly 8 characters, no spaces, and 1 special character, 1 letter and 1 digit. |
|
| 17 |
+Per the tutorial, the first configuration was |
|
| 18 |
+ |
|
| 19 |
+~~~~ shell-session |
|
| 20 |
+$ derivepassphrase vault --length 8 --space 0 --symbol 1 --upper 1 --number 1 \ |
|
| 21 |
+> -p work |
|
| 22 |
+Passphrase: [[I am an insecure master passphrase, but easy to type.]] |
|
| 23 |
+r?9\XQR& |
|
| 24 |
+~~~~ |
|
| 25 |
+ |
|
| 26 |
+… which contained the unsupported special character `&`. |
|
| 27 |
+The stipulations forbid changing the length, but they do allow for the configured number of symbols, uppercase letters and digits to be mutated, and lowercase and uppercase letter counts to be exchanged. |
|
| 28 |
+ |
|
| 29 |
+Some example configurations that might turn out to be workable: |
|
| 30 |
+ |
|
| 31 |
+~~~~ shell-session |
|
| 32 |
+$ derivepassphrase vault --length 8 --space 0 --symbol 3 --upper 3 --number 2 \ |
|
| 33 |
+> -p work |
|
| 34 |
+$ derivepassphrase vault --length 8 --space 0 --symbol 1 --upper 1 --number 6 \ |
|
| 35 |
+> -p work |
|
| 36 |
+$ derivepassphrase vault --length 8 --space 0 --symbol 3 --lower 3 --number 2 \ |
|
| 37 |
+> -p work |
|
| 38 |
+$ derivepassphrase vault --length 8 --space 0 --symbol 2 --upper 2 --lower 2 \ |
|
| 39 |
+> --number 2 -p work |
|
| 40 |
+$ derivepassphrase vault --length 8 --space 0 --symbol 1 --upper 1 --lower 1 \ |
|
| 41 |
+> --number 1 -p work |
|
| 42 |
+~~~~ |
|
| 43 |
+ |
|
| 44 |
+For each such configuration, the user would check if the derived passphrase matches the supported set of special characters, and if so, use this configuration. |
|
| 45 |
+ |
|
| 46 |
+If all such configurations are enumerated without success, then the service name would need to be changed, and the process repeated. |
|
| 47 |
+ |
|
| 48 |
+[BASIC_SETUP_PASSPHRASE]: ../tutorials/basic-setup-passphrase.md |
| ... | ... |
@@ -242,7 +242,7 @@ Other service providers may permit other characters (quite rare) or fewer charac |
| 242 | 242 |
|
| 243 | 243 |
!!! abstract "Further reading" |
| 244 | 244 |
|
| 245 |
- → How to deal with "supported" and "unsupported" special characters (TODO) |
|
| 245 |
+ → [How to deal with "supported" and "unsupported" special characters][SUPPORTED_SPECIAL_CHARACTERS] |
|
| 246 | 246 |
|
| 247 | 247 |
For this case specifically, we restrict ourselves to the dashes as the only permitted special characters, and hope that this passes their passphrase policy. |
| 248 | 248 |
|
| ... | ... |
@@ -305,3 +305,4 @@ This completes the tutorial. |
| 305 | 305 |
As a next step, you may want to [configure the accounts to use a master SSH key instead][BASIC_SETUP_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 |
+[SUPPORTED_SPECIAL_CHARACTERS]: ../how-tos/supported-special-characters.md |