Update README

README.md

@@ -1,58 +1,112 @@
-# Sshecret - Openssh based secrets management
+# Sshecret - Simple Secret management using SSH and RSA Keys
 
-## Motivation
+Managing secrets within a container environment or homelab can be quite complex.
 
-There are many approaches to managing secrets for services, but a lot of these
-either assume you have one of the industry-standard systems like hashicorp vault to manage them centrally.
+As with container orchestration in general, many of the available tools are targetted large enterprise installations and add significant complexity to both the management of secrets themselves, and to the consumers.
 
-For enthusiasts or homelabbers this becomes overkill quickly, and end up
-consuming a lot more time and energy than what feels justified.
+For enthusiasts or homelabbers solutions like Hashicorp Vault become overkill
+quickly, and end up consuming a lot more time and energy than what feels
+justified.
 
 This system has been created to provide a centralized solution that works well-enough.
 
-One clear goal was to have all the complexity on the server-side, and be able to construct a minimal client.
+Sshecret provides a simple, centralized solution for secret storage, and requires only tools that are commonly pre-installed on most linux system.
 
-## Components
+# Concept
+The system uses RSA keys, as generated by openssh, to encrypt secrets for each client.
 
-This system has been designed with modularity and extensibility in mind. It has the following building blocks:
+It uses RSA keys as it is possible to do encryption using only the public key. 
 
-- Password database
-- Password input handler
-- Encryption and key management
+By using a custom SSH server, the consuming servers can fetch a version of a secret encrypted specifically for them.
+
+As the secret is encrypted with RSA keys, it can be decrypted using the openssl command which is commonly available.
+
+This means that while the backend interface can be complex, the to access and decrypt a secret, you can use ssh, and a simple bash script.
+
+# Components
+
+There are three components to Sshecret:
+
+- Password database and admin interface
 - Client secret storage backend
-- Custom ssh server
+- Ssh server for clients to access
 
-### Password database
-Currently a single password database is implemented: Keepass.
+The three systems should be deployed separately for security, with the backend system as the only central component. 
 
-Sshecret can create a database, and store your secrets in it.
+The ssh server that the clients connect to, only has access to encrypted versions of the secrets. 
 
-It only uses a master password for protection, so you are responsible for
-securing the password database file. In theory, the password database file can
-be disconnected after encrypting the passwords for the clients, and these two
-components may be disconnected.
+If it or the backend should be compromised, it wouldn't be possible to extract any clear-text secrets, since only encrypted values are stored, and each encrypted with RSA public key encryption. 
 
-### Password input handler
-Passwords can be randomly generated, they can be read from stdin, or from environment variables.
+## Backend
+The backend system stores the definition of each client, including their public key, and the IP addresses/networks they are allowed to connect from.
+It also stores a version of each secret that the client has access to, encrypted with the public key. It has no knowledge of the unencrypted secrets.
 
-Other methods can be implemented in the future.
+Both the admin interface and the ssh server access this system over a REST API using a token-based authentication method.
 
-### Client secret storage backend
-So far only a simple JSON file based backend has been implemented. It stores one file per client.
-The interface is flexible, and can be extended to databases or anything else really.
+## Password database and admin interface
+The sshecret password database is based on keepass, and the admin interface is available as a simple web interface as well as a REST API.
 
-### Custom SSH server
-A custom SSH based on paramiko is included. This is how the clients receive the encrypted password.
-The client must send a single command over the SSH session equal to the name of the secret.
+This component is primarily responsible for storing the secrets in a keepass database and populating the backend with client-specific encrypted versions.
 
-If permitted to access the secret, it will returned encrypted with the client RSA public key of the client, encoded as base64.
+The admin interface must be secured. It currently supports local user accounts, but will be expanded with OIDC support in the near future.
+
+## Custom SSH server
+To make it easy to fetch secrets sshecret includes a SSH server. 
+
+To fetch a secret, simply ssh to it using the client name as username and the
+registered RSA key as authorization.
+
+Send the command `get_secret` followed by the name of the secret. The ssh server
+will check the client's public key against permitted keys, and check if the
+client is allowed to connect and if the secret is available to it.
+
+The server will answer with a base64 encoded version of the secret.
+
+See `examples/sshecret-client.bash` for an example of a bash script that can be
+used to fetch and decrypt a secret.
+
+Out of the box, only the `get_secret` command is available, however an optional
+command `register` can be enabled to allow registration of a client using the
+SSH interface to make it easy to onboard new clients automatically.
+
+# Configuration
+
+Each subsystem is set up using environment variables.
+
+## Backend
+The location and type of database may be configured. 
+For now, only sqlite is officially supported.
+
+The value shown below is the default value. In a docker setup, you may want to
+create a volume and configure this to a path within the volume to be able to
+perform backups.
+
+    SSHECRET_BACKEND_DATABASE=/path/to/sshecret.db
+    
+    
+While the backend can be placed behind reverse proxy and served with HTTPS, it's
+probably better to have keep it inside an internal container network.
+
+## Admin
+The backend must be generated on the backend before setting up the admin.
+
+    SSHECRET_BACKEND_URL=http://backend:8022
+    SSHECRET_ADMIN_BACKEND_TOKEN: mySuperSecretBackendToken
+    
+
+## Deployment
+
+The system can be deplyed using docker or any other container runtime.
+
+See the examples in the `docker/` folder.
 
-This allows the client to decrypt and get the clear text value easily.
 
 # FAQ
 ## Why not use Age?
-I like age a lot, and it's ability to use more ssh key types is certainly a winner feature.
-However, one goal here is to be able to construct a client with minimal dependencies, and that speaks in favor of the current solution.
+
+I like age a lot, and it's ability to use more ssh key types is certainly a
+winner feature. However, a clear goal of this project is to be able to construct
+a client with minimal dependencies.
 
 Using just RSA keys, you can construct a client using only the following tools:
 - base64
@@ -60,3 +114,5 @@ Using just RSA keys, you can construct a client using only the following tools:
 - ssh
 
 This means that you can create a client using just a shell script.
+
+If age were to be used, the age tool would have to be installed on each client sytem.