From 6229b779a40b484abad22266ce7a73d87280ba85 Mon Sep 17 00:00:00 2001 From: jdreichmann Date: Sun, 7 Jun 2020 17:24:28 +0200 Subject: [PATCH] add documentation --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..58cf712 --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ +# ansible-gpg-vault + +## Purpose + +This is meant to be used as a git submodule, which can easily be included in repos containing ansible vaults. + +It generates a strong passphrase and encrypts it using GPG so only authorized people may open/edit the vaults while still allowing the whole playbook to be world-readable. + +## Setup + +In your project, add this as a submodule. Let's assume we are in `awesome-project/`: + + $ pwd + awesome-project/ + $ git submodule add $this_repo + Cloning into 'awesome-project/ansible-gpg-vault'... + Unpacking objects: 100%, done. + $ ./ansible-gpg-vault/vault.sh init + Specify the inital user who may access the vault + GPG user id: $yourUserIdHere + $ + +Now make sure you instruct ansible to use the vault script when looking for the vault passphrase by editing ansible.cfg to contain: + + [defaults] + + vault_password_file = ansible-gpg-vault/vault.sh + +And then you should be done already! Time to create your first vault with the normal ansible way: + + $ ansible-vault create host_vars/secrets.yml + < $EDITOR opens > + +## Usage + +### Adding users + +You may add users by calling `ansible-gpg-vault/vault.sh add` (interactive) or `ansible-gpg-vault/vault.sh add $NEWUSER` (non-interactive). + +Always ensure that gpg2 knows the user-id on the machine, as key downloading from a keyserver is not implemented yet. + +### Reencrypting + +After a user is added, the file containing ansibles vault passhprase is automatically decrypted and encrypted again. you can trigger this manually using `ansible-gpg-vault/vault.sh reencrypt`. + +### Deleting users + +Deleting is not yet implemented, you can remove users manually by removing their id from `ansible-gpg-vault-store/gpg_ids.list` and then calling `ansible-gpg-vault/vault.sh reencrypt` to reencrypt the passphrase. + +Security notice: when a malicious user has decrypted and saved the passphrase while they had authorized access, they do still have the passphrase and deleting/reencrypting does not protect against this attack. + +## Storage + +The passphrase and list of gpg user-ids are stored in `ansible-gpg-vault-store/` in the top level of the repository, as to not dirty the tree of the submodule and allowing to commit the changes in the repo they are meant to be in. +## Storage + +The passphrase and list of gpg user-ids are stored in `ansible-gpg-vault-store/` in the top level of the repository, as to not dirty the tree of the submodule and allowing to commit the changes in the repo they are meant to be in.