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-passphrase.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-passphrase.md  24)     - exactly 5 digits
docs/tutorials/basic-setup-passphrase.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-passphrase.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-passphrase.md  43) You will need Python 3, and a package installer such as `pip` (bundled with Python), `pipx` or similar.
docs/tutorials/basic-setup-passphrase.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-passphrase.md  76) `derivepassphrase` uses a master passphrase <var>MP</var>, and derives all other passphrases <var>P</var> from <var>MP</var>.

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!