docs/tutorials/basic-setup-passphrase.md (f9a8d37) - derivepassphrase.git

basic-setup-passphrase.md

# Setting up `derivepassphrase vault` for three accounts, with a master passphrase

## The scenario

In this tutorial, we will setup `derivepassphrase` for three services, using a master passphrase and the standard `vault` passphrase derivation scheme.
We will assume the following three services with the following passphrase policies:

-   __email account__

---

- between 12 and 20 characters
    - no spaces
    - 1 upper case letter, 1 lower case letter, 1 digit
    - no character may appear 3 times (or more) in a row

-   __bank account__

---

- only digits
    - exactly 5 digits
    - an additional one-time password via a hardware token ("[two-factor authentication][2FA]")

-   __work account__

---

- exactly 8 characters
    - no spaces
    - 1 special character, 1 letter, 1 digit
    - must be changed every quarter (January, April, July and October) to a different value ("passphrase rotation" or "rollover")
    - must actually be different from the previous *two* passphrases

</div>

[2FA]: https://en.wikipedia.org/wiki/Two-factor_authentication

## Installing `derivepassphrase`

??? note "Note: Shell Notation"

`derivepassphrase` is a command-line application: it runs in the system shell, such as `/bin/sh` on UNIX and Powershell on Windows.

In the following shell session transcripts, `$` and '>' denote the <b>prompt</b> from the system shell for user input.
    Type in *the remainder* of line, but not the prompt itself.
    Other lines are *output lines*, which should appear on your shell.

For Windows-specific commands, we use the `PS>` prompt; otherwise, we use UNIX-style `$` and `>` prompts.

You will need Python 3, and a package installer such as `pip` (bundled with Python), `pipx`, `uv`, etc.

---

=== "pip"

With `pip`, using a "virtual enviroment" in a user-specific configuration directory to avoid clobbering our system configuration:

=== "UNIX (and Cygwin/MSYS, WSL, and Git for Windows)"

The configuration directory is `.venv` within our home directory, i.e., `~/.venv`.

~~~~ shell-session
        $ python3 -m venv ~/.venv
        $ . ~/.venv/bin/activate
        $ pip install derivepassphrase
        ~~~~

If the `pip` step complains that there is no such command, use `python3 -m pip install derivepassphrase` instead.

=== "Windows"

The configuration directory is `.venv` within our application data directory, i.e., `C:\Users\<name>\AppData\Roaming\.venv`.

~~~~ pwsh-session
        PS> python -m venv %APPDATA%\.venv
        PS> & %APPDATA%\.venv\Scripts\Activate.ps1
        PS> python -m pip install derivepassphrase

Note that `derivepassphrase` will only be available in shell sessions where the virtual environment has been activated (in step 2 above).

=== "pipx"

~~~~ shell-session
    $ pipx install derivepassphrase
    ~~~~

=== "uv"

~~~~ shell-session
    $ uv tool install derivepassphrase
    ~~~~

---

Check that the installation was successful.

~~~~ shell-session
$ devirepassphrase vault --version
derivepassphrase 0.5
Using cryptography 44.0.0
Using click 8.1.8

Supported features: master SSH key.
~~~~

(…or similar output.)

## Choosing a master passphrase

`derivepassphrase` uses a master passphrase <var>MP</var>, and derives all other passphrases <var>P</var> from <var>MP</var>.
We shall choose the master passphrase: `I am an insecure master passphrase, but easy to type.`

## Setting up the email account

In `derivepassphrase`, each passphrase configuration contains a *service name*, which is how `derivepassphrase` distinguishes between configurations.
This service name can be chosen freely, but the resulting passphrase depends on the chosen service name.
For our email account, we choose the straightforward service name `email`.

We need to translate the passphrase policy into options for `derivepassphrase`:

- 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.
  Upper case letters (`--upper`), digits (`--number`), symbols (`--symbol`), spaces (`--space`) and dashes (`--dash`) work similarly.
- A policy "spaces *forbidden*" translates to the option `--space 0`.
  Again, other character classes behave similarly.
- 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.
  In particular, `--repeat 1` means no character may be immediately repeated.
  (See the mnemonic below.)
* 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>.
  (`derivepassphrase` does not explicitly choose <var>k</var> for you.)

??? info "Mnemonic: the `--repeat` option"

The `--repeat` option denotes the *total* number of consecutive occurrences of the same character.
    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*.

Examples:

| option        | valid examples         | invalid examples          |
    |:--------------|:-----------------------|:--------------------------|
    | `--repeat 1`  | `abc`, `aba`, `abcabc` | `aa`, `abba`, `ababb`     |
    | `--repeat 4`  | `122333111123`, `4444` | `55555`, `67788888999996` |
    | `--repeat 11` | `01234567899999999999` | `$$$$$$$$$$$$$$$$$$$$$$$` |

For the `email` service, we choose passphrase length 12.
This leads to the command-line options `--length 12 --space 0 --upper 1 --lower 1 --number 1 --repeat 3`.
Because we are using a master passphrase, we also need the `-p` option.

!!! note "Note: interactive input"

In code listings, sections enclosed in `[[...]]` signify input to the program, for you to type or paste in.

Also, it is normal for passphrase prompts to not "echo" the text you type in.

~~~~ shell-session
$ derivepassphrase vault --length 12 --space 0 --upper 1 --lower 1 \
>                        --number 1 --repeat 3 -p email
Passphrase: [[I am an insecure master passphrase, but easy to type.]]
kEFwoD=C?@+7
~~~~

By design, we can re-generate the same passphrase using the same input to `derivepassphrase`:

We can then visit our email provider and change the passphrase to `kEFwoD=C?@+7`.

### Storing the settings to disk

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.

~~~~ shell-session
$ derivepassphrase vault --config --length 12 --space 0 --upper 1 --lower 1 \
>                        --number 1 --repeat 3 email
~~~~

!!! danger "Security risk: use of `-p` and `--config`"

You are **strongly discouraged** from using the `-p` and the `--config` options together to store the master passphrase!
    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!

Check that the settings are stored correctly:

~~~~ shell-session
$ derivepassphrase vault --export -
{"services": {"email": {"length": 12, "repeat": 3, "lower": 1, "upper": 1, "number": 1, "space": 0}}}
~~~~

Once the settings are stored, only the service name and the master passphrase option are necessary:

~~~~ shell-session
$ derivepassphrase vault -p email
Passphrase: [[I am an insecure master passphrase, but easy to type.]]
kEFwoD=C?@+7
~~~~

## Setting up the bank account

We choose the straightforward service name `bank`.
The passphrase policy leads to the command-line options `--length 5 --lower 0 --upper 0 --number 5 --space 0 --dash 0 --symbol 0`.

The additional one-time password is generated by the hardware token, and therefore out of the scope for `derivepassphrase`.

The rest is similar to the `email` account: we configure our stored settings, generate the passphrase, and request the bank change the account passphrase to match the generated passphrase.

~~~~ shell-session
$ derivepassphrase vault --config --length 5 --lower 0 --upper 0 --number 5 \
>                        --space 0 --dash 0 --symbol 0 bank
$ derivepassphrase vault -p bank
Passphrase: [[I am an insecure master passphrase, but easy to type.]]
98517
~~~~

## Setting up the work account

We first take care of the first two constraints (passphrase length and permitted/required characters), then deal with the passphrase change/reuse aspects afterwards.
Again, we start with the straightforward service name `work`, we choose "upper case letters" to fulfill the "1 letter" requirement, and add the options `--length 8 --space 0 --symbol 1 --upper 1 --number 1`.

~~~~ shell-session
$ derivepassphrase vault --length 8 --space 0 --symbol 1 --upper 1 --number 1 \
>                        -p work
Passphrase: [[I am an insecure master passphrase, but easy to type.]]
r?9\XQR&
~~~~

Then we attempt to set the work passphrase to `r?9\XQR&`… but our employer's identity management system returns an error: `illegal character: &`.
What happened?

### Complication 1: What is a (permitted) "special character"?  {#special-character}

`derivepassphrase` considers the characters `!"#$%&'()*+,./:;<=>?@[\]^{|}~-_'` to be permitted special characters.
Other service providers may permit other characters (quite rare) or fewer characters (quite common).
(Service providers may also *not* explicitly say which special characters they permit, except through trial and error.)

!!! abstract "Further reading"

→ How to deal with "supported" and "unsupported" special characters (TODO)

For this case specifically, we restrict ourselves to the dashes as the only permitted special characters, and hope that this passes their passphrase policy.

~~~~ shell-session
$ derivepassphrase vault --length 8 --space 0 --symbol 0 --dash 1 \
>                        --upper 1 --number 1 -p work
Passphrase: [[I am an insecure master passphrase, but easy to type.]]
it90-HPO
~~~~

This works.
For now.

### Complication 2: How to implement passphrase rotation?  {#passphrase-rotation}

`derivepassphrase` can only ever derive one passphrase per configuration, so passphrase rotation cannot be accomplished by reusing the same configuration.
So some part of the configuration---generally the service name---needs to change upon each rotation.

!!! abstract "Further reading"

→ How to deal with regular passphrase rotation (TODO)

We choose to append a very coarse timestamp to the "base" service name `work`: the 4-digit year, a `Q`, and the "quarter" number (1, 2, 3 or 4).
As of October 2024, this leads to the final service name `work-2024Q4`.

~~~~ shell-session
$ derivepassphrase vault --config --length 8 --space 0 --symbol 0 --dash 1 \
>                        --upper 1 --number 1 work-2024Q4
$ derivepassphrase vault -p work-2024Q4
Passphrase: [[I am an insecure master passphrase, but easy to type.]]
-P268G0A
~~~~

## Summary

We have installed `derivepassphrase` and set up three accounts for use with the `vault` passphrase derivation scheme, and the master passphrase `I am an insecure master passphrase, but easy to type.`.
Our configuration should look like this:

~~~~ shell-session
$ derivepassphrase vault --export -
{"services": {"email": {"length": 12, "repeat": 3, "lower": 1, "upper": 1, "number": 1, "space": 0}, "bank": {"length": 5, "lower": 0, "upper": 0, "number": 5, "space": 0, "dash": 0, "symbol": 0}, "work-2024Q4": {"length": 8, "upper": 1, "number": 1, "space": 0, "dash": 1, "symbol": 0}}}
~~~~

We should also get the following output when asking for those passphrases again:

~~~~ shell-session
$ derivepassphrase vault -p email
Passphrase: [[I am an insecure master passphrase, but easy to type.]]
kEFwoD=C?@+7
$ derivepassphrase vault -p bank
Passphrase: [[I am an insecure master passphrase, but easy to type.]]
98517
$ derivepassphrase vault -p work-2024Q4
Passphrase: [[I am an insecure master passphrase, but easy to type.]]
-P268G0A
~~~~

This completes the tutorial.

As a next step, you may want to [configure the accounts to use a master SSH key instead][BASIC_SETUP_SSH_KEY].

[BASIC_SETUP_SSH_KEY]: basic-setup-ssh-key.md "Tutorial: Using a master SSH key with derivepassphrase vault on existing accounts"

derivepassphrase.git

Add a tutorial for using SSH keys with `derivepassphrase vault`