Vanilla example
===============

Pashword contains a default configuration of almost all parameters.
You will see later how to use the command-line interface or your own configuration file to replace the default values.
For now, and thanks to all the preconfigured parameters, you will be able to test the package features with a minimum of effort.

Password configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~

To start, you need to create a file that will contain the (public) information that will allow you to reconstruct your passwords.
This file contains several sections.
Each of these sections corresponds to the information needed to generate a single password.
So you can have more than one account saved in the same configuration file.
Here is an example of a file named ``your-name.conf``:

.. code-block:: ini

   [entity-one.org]
   mail = user@email.address
   date = 2023-07-19
   form = u***-l***-d***

   [entity-two.com]
   user = username
   date = 2022-02-19
   form = u***-l***-d***

The name of the section must be different for each account.
It is recommended to name the sections with the hostname of the server on which your account is registered.
The only mandatory entry is the one called ``form``.
This entry defines the format of the generated password.
To see what the metacharacters correspond to, look at the section ``pashword.core.sets`` of the package configuration file `default.conf <https://gitlab.com/dustils/pashword/-/blob/main/src/pashword/default.conf>`_.
Even if it is not mandatory, it is advisable to keep the sections ``mail`` (or ``user``) and ``date``.
This will allow you to remember your login name and the date you last changed your password.

Hashing and modus operandi
~~~~~~~~~~~~~~~~~~~~~~~~~~

Passwords are generated by a hashing algorithm from a secret key known only by the user to which is concatenated a cryptographic salt made up of the unencrypted information contained in the configuration file.
To clarify, the secret key and the configuration file are the inputs to the program, and the passwords for your accounts are the outputs.
Here are a few notions specific to the use of Pashword:

* Only one secret key is used to reveal the passwords of the accounts defined in a configuration file.
* You do not choose the value of your passwords. You only choose their format (according to what is allowed on this or that site).
* Changing an entry in a section of the configuration file will change the password associated with the section.
* Since a password is an hash of your secret key (to which we add a salt specific to the account), it is technically impossible (or at least extremely complicated) to deduce your secret key from a leaked password.
* Since a unique salt (consisting of the section name and its entries) is used for each account, the passwords generated from the different sections will all be different.

To create a password you must:

1. Add the section corresponding to the new account in the configuration file.
2. Run the program to discover the value of your password.

To change a password you must:

1. Run the program to get the value of your old password.
2. Add the section corresponding to the account in the configuration file.
3. Run again the program to get the new value of your password.

Read a password book
~~~~~~~~~~~~~~~~~~~~

To display your passwords, run the following command:

.. code-block:: bash

   pashword read your-name.conf

In order to limit the number of sections to be displayed, the program will first ask you for a matching pattern.
As for matching filenames on POSIX systems, use the ``*`` character as a wildcard.
Then the program will ask you to enter your secret key before displaying your passwords.
As it is, the program has no way of knowing if you have entered the right secret key or not.
It will generate the passwords, but they will be wrong if there is a typo in the secret key.

Sort a password book
~~~~~~~~~~~~~~~~~~~~

You can sort the sections contained in a configuration file alphabetically with the following command.

.. code-block:: bash

   pashword sort your-name.conf
