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-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-passphrase.md  45) ??? info "Info: Current supported Python versions"
docs/tutorials/basic-setup-passphrase.md  46) 
docs/tutorials/basic-setup-passphrase.md  47)     ![See PyPI.][CURRENT_PYTHON]

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

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

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

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

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

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

docs/tutorials/basic-setup-password.md    68) 
docs/tutorials/basic-setup-password.md    69) Check that the installation was successful.
docs/tutorials/basic-setup-password.md    70) 
docs/tutorials/basic-setup-password.md    71) ~~~~ shell-session
docs/tutorials/basic-setup-password.md    72) $ devirepassphrase --version

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

docs/tutorials/basic-setup-password.md    74) ~~~~
docs/tutorials/basic-setup-password.md    75) 
docs/tutorials/basic-setup-password.md    76) (…or similar output.)
docs/tutorials/basic-setup-password.md    77) 

docs/tutorials/basic-setup-passphrase.md  78) ??? info "Info: Current `derivepassphrase` version"
docs/tutorials/basic-setup-passphrase.md  79) 
docs/tutorials/basic-setup-passphrase.md  80)     ![See PyPI.][CURRENT_VERSIONS]
docs/tutorials/basic-setup-passphrase.md  81) 
docs/tutorials/basic-setup-passphrase.md  82) [CURRENT_VERSIONS]: https://img.shields.io/pypi/v/derivepassphrase.svg?label=derivepassphrase
docs/tutorials/basic-setup-passphrase.md  83) [CURRENT_PYTHON]: https://img.shields.io/pypi/pyversions/derivepassphrase.svg
docs/tutorials/basic-setup-passphrase.md  84) 

docs/tutorials/basic-setup-password.md    85) ## Choosing a master passphrase
docs/tutorials/basic-setup-password.md    86) 

docs/tutorials/basic-setup-passphrase.md  87) `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    88) We shall choose the master passphrase: `I am an insecure master passphrase, but easy to type.`
docs/tutorials/basic-setup-password.md    89) 
docs/tutorials/basic-setup-password.md    90) ## Setting up the email account
docs/tutorials/basic-setup-password.md    91) 
docs/tutorials/basic-setup-password.md    92) In `derivepassphrase`, each passphrase configuration contains a *service name*, which is how `derivepassphrase` distinguishes between configurations.
docs/tutorials/basic-setup-password.md    93) This service name can be chosen freely, but the resulting passphrase depends on the chosen service name.
docs/tutorials/basic-setup-password.md    94) For our email account, we choose the straightforward service name `email`.
docs/tutorials/basic-setup-password.md    95) 
docs/tutorials/basic-setup-password.md    96) We need to translate the passphrase policy into options for `derivepassphrase`:
docs/tutorials/basic-setup-password.md    97) 

docs/tutorials/basic-setup-password.md    98) - 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    99)   Upper case letters (`--upper`), digits (`--number`), symbols (`--symbol`), spaces (`--space`) and dashes (`--dash`) work similarly.

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

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

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

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

docs/tutorials/basic-setup-password.md   105) * 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   106)   (`derivepassphrase` does not explicitly choose <var>k</var> for you.)

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

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

docs/tutorials/basic-setup-password.md   111)     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   112) 
docs/tutorials/basic-setup-password.md   113)     Examples:
docs/tutorials/basic-setup-password.md   114) 
docs/tutorials/basic-setup-password.md   115)     | option        | valid examples         | invalid examples          |
docs/tutorials/basic-setup-password.md   116)     |:--------------|:-----------------------|:--------------------------|
docs/tutorials/basic-setup-password.md   117)     | `--repeat 1`  | `abc`, `aba`, `abcabc` | `aa`, `abba`, `ababb`     |
docs/tutorials/basic-setup-password.md   118)     | `--repeat 4`  | `122333111123`, `4444` | `55555`, `67788888999996` |
docs/tutorials/basic-setup-password.md   119)     | `--repeat 11` | `01234567899999999999` | `$$$$$$$$$$$$$$$$$$$$$$$` |
docs/tutorials/basic-setup-password.md   120) 
docs/tutorials/basic-setup-password.md   121) 

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

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