.gitattributes

@@ -1,2 +1,4 @@
 *.enc filter=lfs diff=lfs merge=lfs -text
 *.cert filter=lfs diff=lfs merge=lfs -text
+overview.png filter=lfs diff=lfs merge=lfs -text
+overview.svg filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1 +1,77 @@
 # Coffer 
+[![Build Status](https://drone.friedl.net/api/badges/incubator/coffer/status.svg)](https://drone.friedl.net/incubator/coffer)
+
+Coffer is a collection of tools for the simple but secure management of
+application configuration.
+
+It is meant to be flexible and simple, hence does not assume much about your
+environment. Especially, you don't need a kubernetes cluster for running coffer.
+Coffer runs directly on your server, just as well as in a containerized setup or
+a full kubernetes cluster. The only thing Coffer needs is a TCP connection
+between the `coffer-server` (securely holding your configuration) and the
+`coffer-client` (retrieving configuration and setting up your application).
+
+## Overview
+![](overview.png)
+
+## The Parts of Coffer
+Coffer is split into 3 binaries and a supporting library:
+
+* `coffer-server`: The `coffer-server` securely stores configuration data and
+  hands them out to `coffer-clients` upon request
+* `coffer-client`: A `coffer-client` requests configuration data from a
+  `coffer-server`, configures the application and may also start it up
+* `coffer-companion`: A helper for generating certificates and encrypting
+  configuration data
+* `coffer-common`: A common library for all binaries containing common
+  cryptographic operations, protocol code and interface definitions
+
+## Security
+Coffer does not rely on a secure connection or any specifics of the environment.
+Instead security is provided by a basic public key cryptography scheme. This
+gives you, the user, the flexibility to set up your ecosystem according to your
+own security needs.
+
+### Certificates
+Certificates in coffer are the just a keypair consisting of a public and private
+key as used by public key cryptography. So, basically, a certificate is nothing
+more than a tuple of two primes.
+
+Certificates in coffer can be generated by the `coffer-companion`. Every
+`coffer-server` and `coffer-client` need their own certificate. Security
+in coffer squarely depends on these certificates being kept secret.
+
+### Configuration
+Configuration can be written in [toml](https://github.com/toml-lang/toml)
+format. It is secured by encrypting it with the public key of the
+`coffer-server`. This can be done by invoking the `coffer-companion`.
+
+Encrypted configuration can be conveniently stored in VCS (e.g. via git-lfs)
+with your application. As long as the server certificate stays private.
+
+### Communication
+The communication between a `coffer-server` and a `coffer-client` is not and
+does not need to be secured. A `coffer-server` associates configuration data
+with the public keys of `coffer-clients`. Upon request of configuration data the
+server sends back the configuration encrypted with the clients public key. Only
+a client in posession of the corresponding private key can read the response.
+
+### Trust Anchors
+It is worth mentioning some things about trust anchors. Every cryptography
+scheme, no matter how sophisticated, needs, at some point, something that can be
+trusted. In case of HTTPS this is provided by central certificate authorities.
+In case of the encrypted letters to your best friend this might be a pre-shared
+password transmitted over phone in 1972.
+
+From a coffer perspective keys can be trusted. That is, coffer assumes that
+certificates are distributed and kept secret according to your threat model. An
+attacker in control of a certificate can steal secret configuration!
+
+Coffer does not assume a trust anchor for you. Instead, you are free to choose
+your own trust anchor according. In a simple personal server setup this might
+mean just distributing certificates by hand. In a more complex, corporate
+environment you may want to set up a secure, central authority. 
+
+Trust anchors are a trade-off between convenience, complexity and security.
+Coffer lets _you_ choose where along these axis you put your trust anchor.
+