add documentation

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.