derivepassphrase.git

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

docs/tutorials/basic-setup-password.md  17)     * no character may appear 3 times (or more) in a row

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

docs/tutorials/basic-setup-password.md  43) You will need Python 3.9 or later, and a package installer such as `pip` (bundled with Python), `pipx` or similar.

docs/tutorials/basic-setup-password.md  44) 

docs/tutorials/basic-setup-password.md  45) ---

docs/tutorials/basic-setup-password.md  46) 

docs/tutorials/basic-setup-password.md  47) === "pip"

docs/tutorials/basic-setup-password.md  48) 

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

docs/tutorials/basic-setup-password.md  64) 
docs/tutorials/basic-setup-password.md  65) Check that the installation was successful.
docs/tutorials/basic-setup-password.md  66) 
docs/tutorials/basic-setup-password.md  67) ~~~~ shell-session
docs/tutorials/basic-setup-password.md  68) $ devirepassphrase --version

docs/tutorials/basic-setup-password.md  69) derivepassphrase, version 0.3.0

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

docs/tutorials/basic-setup-password.md  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.

docs/tutorials/basic-setup-password.md  88)   Upper case letters (`--upper`), digits (`--number`), symbols (`--symbol`), spaces (`--space`) and dashes (`--dash`) work similarly.

docs/tutorials/basic-setup-password.md  89) - A policy "spaces *forbidden*" translates to the option `--space 0`.

docs/tutorials/basic-setup-password.md  90)   Again, other character classes behave similarly.

docs/tutorials/basic-setup-password.md  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.
docs/tutorials/basic-setup-password.md  92)   In particular, `--repeat 1` means no character may be immediately repeated.

docs/tutorials/basic-setup-password.md  93)   (See the mnemonic below.)

docs/tutorials/basic-setup-password.md  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>.

docs/tutorials/basic-setup-password.md  95)   (`derivepassphrase` does not explicitly choose <var>k</var> for you.)

docs/tutorials/basic-setup-password.md  96) 

docs/tutorials/basic-setup-password.md  97) ??? note "Mnemonic: the `--repeat` option"
docs/tutorials/basic-setup-password.md  98) 
docs/tutorials/basic-setup-password.md  99)     The `--repeat` option denotes the *total* number of consecutive occurrences of the same character.

docs/tutorials/basic-setup-password.md 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*.

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

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

docs/tutorials/basic-setup-password.md 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!