Implement feedback on the basic setup (passphrase) tutorial
Marco Ricci commited on 2024-10-16 00:29:21
Zeige 1 geänderte Dateien mit 21 Einfügungen und 6 Löschungen.
Fix typos and outdated command output. Add a (hidden by default) short explanation, mnemonic and examples for the `--repeat` option, which actually denotes maximum consecutive occurrence, not additional allowed repetitions.
- docs/tutorials/basic-setup-password.md 205129e..b060117
| ... | ... |
@@ -14,7 +14,7 @@ We will assume the following three services with the following passphrase polici |
| 14 | 14 |
- between 12 and 20 characters |
| 15 | 15 |
- no spaces |
| 16 | 16 |
- 1 upper case letter, 1 lower case letter, 1 digit |
| 17 |
- * no character immediately repeated more than 3 times |
|
| 17 |
+ * no character may appear 3 times (or more) in a row |
|
| 18 | 18 |
|
| 19 | 19 |
- __bank account__ |
| 20 | 20 |
|
| ... | ... |
@@ -59,7 +59,7 @@ Check that the installation was successful. |
| 59 | 59 |
|
| 60 | 60 |
~~~~ shell-session |
| 61 | 61 |
$ devirepassphrase --version |
| 62 |
-derivepassphrase, version 0.2.0 |
|
| 62 |
+derivepassphrase, version 0.3.0 |
|
| 63 | 63 |
~~~~ |
| 64 | 64 |
|
| 65 | 65 |
(…or similar output.) |
| ... | ... |
@@ -77,15 +77,30 @@ For our email account, we choose the straightforward service name `email`. |
| 77 | 77 |
|
| 78 | 78 |
We need to translate the passphrase policy into options for `derivepassphrase`: |
| 79 | 79 |
|
| 80 |
-- A policy "(at least) `n` upper case letters" translates to the option `--lower n`, for any `n` greater than 0. |
|
| 81 |
- Lower case letters (`--upper`), digits (`--number`), symbols (`--symbol`), spaces (`--space`) and dashes (`--dash`) work similarly. |
|
| 80 |
+- A policy "(at least) `n` lower case letters" translates to the option `--lower n`, for any `n` greater than 0. |
|
| 81 |
+ Upper case letters (`--upper`), digits (`--number`), symbols (`--symbol`), spaces (`--space`) and dashes (`--dash`) work similarly. |
|
| 82 | 82 |
- A policy "spaces *forbidden*" translates to the option `--space 0`. |
| 83 | 83 |
Again, other character classes behave similarly. |
| 84 |
-- A policy "no character immediately repeated more than `n` times" translates to the option `--repeat n`, for any `n` greater than 0. |
|
| 84 |
+- A policy "no character may appear `n` times (or more) in a row" translates to the option `--repeat n-1`, for any `n` greater than 1. |
|
| 85 | 85 |
In particular, `--repeat 1` means no character may be immediately repeated. |
| 86 |
+ (See the mnemonic below.) |
|
| 86 | 87 |
* A policy "between `n` and `m` characters long" translates to `--length k`, for any `k` between `n` and `m` which you choose. |
| 87 | 88 |
(`derivepassphrase` does not explicitly choose a passphrase length for you.) |
| 88 | 89 |
|
| 90 |
+??? note "Mnemonic: the `--repeat` option" |
|
| 91 |
+ |
|
| 92 |
+ The `--repeat` option denotes the *total* number of consecutive occurrences of the same character. |
|
| 93 |
+ Or alternatively: if you request `--repeat n`, then `derivepassphrase` will *avoid* deriving any passphrase that repeats a character *another `n` times*. |
|
| 94 |
+ |
|
| 95 |
+ Examples: |
|
| 96 |
+ |
|
| 97 |
+ | option | valid examples | invalid examples | |
|
| 98 |
+ |:--------------|:-----------------------|:--------------------------| |
|
| 99 |
+ | `--repeat 1` | `abc`, `aba`, `abcabc` | `aa`, `abba`, `ababb` | |
|
| 100 |
+ | `--repeat 4` | `122333111123`, `4444` | `55555`, `67788888999996` | |
|
| 101 |
+ | `--repeat 11` | `01234567899999999999` | `$$$$$$$$$$$$$$$$$$$$$$$` | |
|
| 102 |
+ |
|
| 103 |
+ |
|
| 89 | 104 |
For the `email` service, we choose passphrase length 12. |
| 90 | 105 |
This leads to the command-line options `--length 12 --space 0 --upper 1 --lower 1 --number 1 --repeat 3`. |
| 91 | 106 |
Because we are using a master passphrase, we also need the `-p` option. |
| ... | ... |
@@ -126,7 +141,7 @@ $ derivepassphrase vault --config --length 12 --space 0 --upper 1 --lower 1 \ |
| 126 | 141 |
!!! warning "Warning: `-p` and `--config`" |
| 127 | 142 |
|
| 128 | 143 |
Do **not** use the `-p` and the `--config` options together to store the master passphrase! |
| 129 |
- The configuration is assumed to *not contain sensitive contents* and is *not encrypted*, so your master passphrase is then visible to *anyone* with appropriate priviledges! |
|
| 144 |
+ The configuration is assumed to *not contain sensitive contents* and is *not encrypted*, so your master passphrase is then visible to *anyone* with appropriate privileges! |
|
| 130 | 145 |
|
| 131 | 146 |
Check that the settings are stored correctly: |
| 132 | 147 |
|
| 133 | 148 |