pgen/README.md

# PGen - Client/Server password management over SSH

Repeatable password generation with defacto synchronization using a client and
server model. Actual passwords don't get stored anywhere. They are instead
generated at execution time using a predictable set of rules and parameters to
create extremely strong, programatically generated passwords over a secure SSH
tunnel.

## Work in progress

At the time of writing, the project has barely started and is nowhere near ready
for use.

## Principles of operation

PGen takes a novel approach to password management. It has a simple client and
server model where neither end actually stores the generated passwords.

Authentication to the server is done using keys stored in the SSH Agent. This
allows for offloading the work of providing a keyring or top-quality encryption
to standard SSH utilities.

Given that the user would be expected to protect their SSH keys with at least as
much rigor as any master password, it eliminates the need for a distinct one. Of
course a password protected private key would still be recommended.

The client collects all necessary parameters and then executes a SSH connection
to the server, passing those parameters.

The server is a dedicated user within a chroot housing only the absolute minimum
environment needed execute and then exit. This provides enhanced security by
using only the PGen server script as the shell, so getting access to a login
shell should not be possible.

The necessary parameters collected by the client are included as environment
variables which are forwarded in the SSH session. It supports multiple profiles
by maintaining a separate parameters list for each public key fingerprint.

Given the parameters from the connecting user, the server programatically
generates the passwords and maintains a database of previous configurations. By
maintaining this list it means that any client with the same public public key
fingerprint will have access to the same list. This provides the defacto
syncronization. None of the 

Generation uses a strong cipher to hash various parameters, then build the
password from the list of approved characters.

The server will return the password to the client over the tunnel. The client
can then print the password as plain-text for copying, or add it directly to
the clipboard (Xorg or wlroots).

## Installation

Installation is not currently possible, but will be provided through a unified
installation script.

## Usage

Targetted usage would be:

```
$ pgen service_key [options]
```

The `service_key` will be a unique identifier which gets stored on the server
and associated with the relevant settings so that in subsequent runs, the
combination of these settings and parameters provided every time by the client
will be able repeatably generate the same password.

Options and features targetted for an initial release are:

  * Plain-text parameter database
  * Option to overwrite any individual parameter at run-time without changing
    the values in the database
  * Option to generate a new password using identical parameters by making a
    timestamp be the only parameter that gets updated
  * Sufficient warnings before overwriting any changes to the database
  * Listing of existing service keys
  * Listing of parameters assigned to a key
  * Additional security using a salt file. This would result in unique passwords
    even when the SSH fingerprint and all other parameters match
  * Strong cipher support when actually hashing parameters
  * Suitably strong algorithm for converting 
  * Augmentation rules. Allow for a set of rules to guarantee compatibility. If
    a site requires certain special characters, those are not guaranteed to be
    included. Instead, declaring an option like "--requireone=&*()" to include
    at least one of those listed or "--requirespecial=2" at least 2 of any. Log
    these rules for future usage.
  * Quick/quite mode. An option to run with a basic set of parameters which
    avoids all interactive prompts. Use parameters which should be strong while
    also being widely accepted.
  * Throwaway mode option. Simply don't store the password parameters.

# Contributing

Contributions are welcome through Gitea at:

    https://git.john.me.tz/jpm/pgen

# License and Copyright

Copyright (c) 2022 John Mertz <git@john.me.tz>

Licensed under GPLv2 or later. See LICENSE.