Initial outline with goals

README.md

@@ -1,2 +1,104 @@
-# pgen
+# 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.