derivepassphrase.git

1) # Tutorial: setting up `derivepassphrase vault` for three accounts, with a master passphrase
2) 
3) ## The scenario
4) 
5) In this tutorial, we will setup `derivepassphrase` for three services, using a master passphrase and the standard `vault` passphrase derivation scheme.
6) We will assume the following three services with the following passphrase policies:
7) 
8) <div class="grid cards" markdown>
9) 
10) -   __email account__
11) 
12)     ---
13) 
14)     - between 12 and 20 characters
15)     - no spaces
16)     - 1 upper case letter, 1 lower case letter, 1 digit

17)     * no character may appear 3 times (or more) in a row

18) 
19) -   __bank account__
20) 
21)     ---
22) 
23)     - only digits
24)     * exactly 5 digits
25)     * an additional one-time password via a hardware token ("[two-factor authentication][2FA]")
26) 
27) -   __work account__
28) 
29)     ---
30) 
31)     - exactly 8 characters
32)     * no spaces
33)     - 1 special character, 1 letter, 1 digit
34)     - must be changed every quarter (January, April, July and October) to a different value ("passphrase rotation" or "rollover")
35)     - must actually be different from the previous *two* passphrases
36) 
37) </div>
38) 
39) [2FA]: https://en.wikipedia.org/wiki/Two-factor_authentication
40) 
41) ## Installing `derivepassphrase`
42) 

43) You will need Python 3.9 or later, and a package installer such as `pip` (bundled with Python), `pipx` or similar.

44) 

45) ---

46) 

47) === "pip"

48) 

49)     With `pip`, using a "virtual enviroment" at `~/.venv` to avoid clobbering our system configuration:
50) 
51)     ~~~~ shell-session
52)     $ python3 -m venv ~/.venv
53)     $ . ~/.venv/bin/activate
54)     $ pip install derivepassphrase
55)     ~~~~
56) 
57) === "pipx"
58) 
59)     ~~~~ shell-session
60)     $ pipx install derivepassphrase
61)     ~~~~
62) 
63) ---

64) 
65) Check that the installation was successful.
66) 
67) ~~~~ shell-session
68) $ devirepassphrase --version

69) derivepassphrase, version 0.3.0

70) ~~~~
71) 
72) (…or similar output.)
73) 
74) ## Choosing a master passphrase
75) 
76) `derivepassphrase` uses a master passphrase `MP`, and derives all other passphrases `P` from `MP`.
77) We shall choose the master passphrase: `I am an insecure master passphrase, but easy to type.`
78) 
79) ## Setting up the email account
80) 
81) In `derivepassphrase`, each passphrase configuration contains a *service name*, which is how `derivepassphrase` distinguishes between configurations.
82) This service name can be chosen freely, but the resulting passphrase depends on the chosen service name.
83) For our email account, we choose the straightforward service name `email`.
84) 
85) We need to translate the passphrase policy into options for `derivepassphrase`:
86) 

87) - A policy "(at least) <var>n</var> lower case letters" translates to the option <code>-<span/>-lower <var>n</var></code>, for any <var>n</var> > 0.

88)   Upper case letters (`--upper`), digits (`--number`), symbols (`--symbol`), spaces (`--space`) and dashes (`--dash`) work similarly.

89) - A policy "spaces *forbidden*" translates to the option `--space 0`.

90)   Again, other character classes behave similarly.

91) - A policy "no character may appear <var>n</var> times (or more) in a row" translates to the option <code>-<span/>-repeat (<var>n</var> − 1)</code>, for any <var>n</var> > 1.
92)   In particular, `--repeat 1` means no character may be immediately repeated.

93)   (See the mnemonic below.)

94) * A policy "between <var>n</var> and <var>m</var> characters long" translates to <code>-<span/>-length <var>k</var></code>, for any choice of <var>k</var> which satisfies <var>n</var> ≤ <var>k</var> ≤ <var>m</var>.

95)   (`derivepassphrase` does not explicitly choose <var>k</var> for you.)

96) 

97) ??? note "Mnemonic: the `--repeat` option"
98) 
99)     The `--repeat` option denotes the *total* number of consecutive occurrences of the same character.

100)     Or alternatively: if you request <code>-<span/>-repeat <var>n</var></code>, then `derivepassphrase` will *avoid* deriving any passphrase that repeats a character *another <var>n</var> times*.

101) 
102)     Examples:
103) 
104)     | option        | valid examples         | invalid examples          |
105)     |:--------------|:-----------------------|:--------------------------|
106)     | `--repeat 1`  | `abc`, `aba`, `abcabc` | `aa`, `abba`, `ababb`     |
107)     | `--repeat 4`  | `122333111123`, `4444` | `55555`, `67788888999996` |
108)     | `--repeat 11` | `01234567899999999999` | `$$$$$$$$$$$$$$$$$$$$$$$` |
109) 
110) 

111) For the `email` service, we choose passphrase length 12.
112) This leads to the command-line options `--length 12 --space 0 --upper 1 --lower 1 --number 1 --repeat 3`.
113) Because we are using a master passphrase, we also need the `-p` option.
114) 
115) !!! note "Note: interactive input"
116) 
117)     In code listings, sections enclosed in `[[...]]` signify input to the program, for you to type or paste in.
118) 
119)     Also, it is normal for passphrase prompts to not "echo" the text you type in.
120) 
121) ~~~~ shell-session
122) $ derivepassphrase vault --length 12 --space 0 --upper 1 --lower 1 \
123) >                        --number 1 --repeat 3 -p email
124) Passphrase: [[I am an insecure master passphrase, but easy to type.]]
125) kEFwoD=C?@+7
126) ~~~~
127) 
128) By design, we can re-generate the same passphrase using the same input to `derivepassphrase`:
129) 
130) ~~~~ shell-session
131) $ derivepassphrase vault --length 12 --space 0 --upper 1 --lower 1 \
132) >                        --number 1 --repeat 3 -p email
133) Passphrase: [[I am an insecure master passphrase, but easy to type.]]
134) kEFwoD=C?@+7
135) ~~~~
136) 
137) We can then visit our email provider and change the passphrase to `kEFwoD=C?@+7`.
138) 
139) ### Storing the settings to disk
140) 
141) Because it is tedious to memorize and type in the correct settings to re-generate this passphrase, `derivepassphrase` can optionally store these settings, using the `--config` option.
142) 
143) ~~~~ shell-session
144) $ derivepassphrase vault --config --length 12 --space 0 --upper 1 --lower 1 \
145) >                        --number 1 --repeat 3 email
146) ~~~~
147) 
148) !!! warning "Warning: `-p` and `--config`"
149) 
150)     Do **not** use the `-p` and the `--config` options together to store the master passphrase!

151)     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!