From cb5b5550725fbdb605041f9bd9ab7d2e0e4fb590 Mon Sep 17 00:00:00 2001 From: gve Date: Tue, 23 Apr 2019 09:40:45 +0200 Subject: [PATCH] add usage part --- docs/usage.org | 215 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 docs/usage.org diff --git a/docs/usage.org b/docs/usage.org new file mode 100644 index 0000000..723598e --- /dev/null +++ b/docs/usage.org @@ -0,0 +1,215 @@ +#+TITLE: vaultify usage +#+OPTIONS: +#+AUTHOR: Georg vom Endt (krysopath@gmail.com) + +* Installation +This section explains different installation methods. +** Requirements + - python3.6, python3.7 + - pip + - docker (obsoletes the above) + +** from pypi +Most implementers will fetch the package from pypi and build their own +things on another layer. +#+BEGIN_SRC shell +pip3 install vaultify +#+END_SRC + +** from git +Alternatively fetch the sources from github to develop your own +adapter classes. +#+BEGIN_SRC shell +git clone git@github.com:krysopath/vaultify.git +#+END_SRC +** os dependencies +These tools can greatly speed up local development, when used in +conjunction via ~make~, so install them. They can overwhelm you with +output, too. + +*** ubuntu +#+BEGIN_SRC shell +apt install make entr yamllint pylint bandit +#+END_SRC + +* usage + +** first steps + +1. either create a virtualenv and install requirements.txt or +2. run `docker build .` + +Before using `vaultify` you need to export these into your environment: + +#+BEGIN_SRC +export VAULTIFY_PROVIDER= +export VAULTIFY_CONSUMER= +export VAULTIFY_LOGLEVEL= # default is info +#+END_SRC + +>**r**ead **t**he **f**riendly **m**anual for the chosen Provider & Consumer, too + +Then just run: +#+BEGIN_SRC +./entry.py +#+END_SRC + + + +** feature overview + +In this table you find an info about which Provider/Consumer +pairs are supported: + +| pairs | GPG | OpenSSL | Vault | +|--------------+-----+---------+-------| +| DotEnvWriter | y | y | y | +| EnvRunner | y | y | y | +| JsonWriter | y | y | y | + + +Assuming the pattern holds, we expect always full compatibility +between any Provider/Consumer pair. + +** providers + +Providers are all classes, that create some `vaultify`-compliant dictionary, +which then is used by `vaultify` consumers. + +*** GPGProvider + +This Provider can decrypt symmetrically encrypted files, created with `gpg`. + +Adhere to this format: +#+BEGIN_SRC +KEY1=VAL1 +[...] +KEYN=VALN +#+END_SRC + +To encrypt such a file, execute: +#+BEGIN_SRC +gpg --symmetric +#+END_SRC + +Below are environment variables, that are needed by this provider: + +#+BEGIN_SRC +# this will be used as the passphrase to gpg +export VAULTIFY_SECRET= +#+END_SRC + +*** OpenSSLProvider + +This provider can decrypt symmetrically encrypted files, created with `openssl` + +Adhere to this format: +#+BEGIN_SRC +KEY1=VAL1 +[...] +KEYN=VALN +#+END_SRC + +To encrypt such a file, execute: +```bash +#+BEGIN_SRC +openssl enc -aes-256-cbc -salt -a -in -out .enc +#+END_SRC +``` + +> Do not use aes-256-cbc, if there is aes-256-gcm available in your openssl. +This prevents Padding Oracle attacks against the cipher text. Currently +setting the aes cipher is not possible in `vaultify` but will be made, when +the default openssl library ships with AEAD compiled. If your OpenSSL CLI +supports aes-256-gcm, please file a bug report against vaultify. + +Below are environment variables, that are needed by this provider: + +```bash +#+BEGIN_SRC +#+END_SRC +# this will be used as the passphrase to openssl +export VAULTIFY_SECRET= +``` + +*** VaultProvider + +This provider fetches secrets from HashiCorp Vault API. + + +Below are environment variables, that are needed by this provider: + +#+BEGIN_SRC +# set this to a reachable vault API +export VAULT_ADDR= +# set this to nodes in vaults kv engine, where you do have perms for READ +export VAULT_PATHS= + +# if you do not set $VAULTIFY_SECRET, then +export VAULT_TOKEN= +#+END_SRC + +`VaultProvider` will use `VAULTIFY_SECRET` or `VAULT_TOKEN` for authentication, +in that order. + +** consumers + +are all classes that operate on a `vaultify` compliant dictionary, to +**somehow** use the secrets in there for the greater good. + +*** DotEnvWriter + +This simplest form of vaultification just creates a plaintext file with +the form of + +#+BEGIN_SRC +export Key1=Value1 +[...] +export KeyN=ValueN +#+END_SRC + +for all N keys in the provided dictionary. + +Below are environment variables, that are needed by this consumer: + +#+BEGIN_SRC +# this controls the location of the dotenv file +export VAULTIFY_DESTFILE=/a/path/to/where/secrets.env +#+END_SRC + + +*** JsonWriter + +This consumer is very similar to the `DotEnvWriter`, but produces a +json file instead. + +Below are environment variables, that are needed by this consumer: + +```bash +#+BEGIN_SRC +#+END_SRC +# this controls the location of the dotenv file +export VAULTIFY_DESTFILE=/a/path/to/where/secrets.json +``` + +*** EnvRunner + +If you want to just execute a process with some secrets, then +`EnvRunner` consumer will run a subprocess with an enriched +environment for you. + +>In that sense `EnvRunner` doubles as an entry point for docker runtimes. + +Choose this, if you want to prevent any kind of secret persistence. + +> one might not like having docker `tmpfs` volumes swapped or +accidentally persist after a crash + +Below are environment variables, that are needed by this consumer: + +#+BEGIN_SRC +# this controls the invocation of the target process. +export VAULTIFY_TARGET='/a/path/where/a/secret/hungry/binary --with-some flag wants-execution' +#+END_SRC + +Currently `EnvRunner` does not support interactive commands.