From 98f82ef13e476efaddef522f505dc3272d4e1c59 Mon Sep 17 00:00:00 2001 From: Armin Friedl Date: Sun, 9 Feb 2020 16:17:04 +0100 Subject: [PATCH] [coffer] Update Readme --- .gitattributes | 2 ++ README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++- overview.png | 3 ++ overview.svg | 3 ++ 4 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 overview.png create mode 100644 overview.svg diff --git a/.gitattributes b/.gitattributes index 2c752ed..70e065a 100644 --- a/.gitattributes +++ b/.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 diff --git a/README.md b/README.md index c331c35..87cf142 100644 --- a/README.md +++ b/README.md @@ -1 +1,77 @@ -# Coffer +# 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. + diff --git a/overview.png b/overview.png new file mode 100644 index 0000000..7df19d7 --- /dev/null +++ b/overview.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4f94bbbadfc6999de61a0a7c96f3d6ed6ac8ba2f00cbeb719faf8d8d3c83a4dd +size 52769 diff --git a/overview.svg b/overview.svg new file mode 100644 index 0000000..9413c1e --- /dev/null +++ b/overview.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:20e3bc8d9a769d67cbfab6f75cd3c403630a527a42c33767e1b4e1597b336167 +size 46743