ansible/README_vault.md

   1 Secrets and Vaults
   2 ==================
   3
   4 All secrets are stored inside encrypted ansible vault files which live in
   5 `host_vars`, `group_vars` or inside the `secrets` directory.
   6 Access to the vault files is controlled via GPG keys. Anybody who uses this
   7 ansible repository needs to have a GPG key.
   8
   9
  10 Creating a GPG key
  11 ------------------
  12
  13 You can use the following command to generate a new GPG key:
  14
  15 ```
  16 # gpg2 --full-gen-key
  17    - select "RSA and RSA" as kind (should be option: 1)
  18    - set keysize to: 4096
  19    - set key expiration to: 2y
  20    - set Real name and eMail address
  21    - set a passphrase for the key (please use a strong passphrase!!!)
  22 ```
  23
  24 This command prints the fingerprint and other information about the newly
  25 generated key. In the line starting with pub you can find the key ID. This
  26 ID can be used to uniquely identify your key. Here is a sample output:
  27
  28 ```
  29 pub   rsa4096/0x1234567812345678 2017-01-01 [SC] [expires: 2019-01-01]
  30       Key fingerprint = 1234 5678 1234 5678 1234  5678 1234 5678 1234 5678
  31 uid                   [ unknown] Firstname Lastname <lastname@example.com>
  32 sub   rsa4096/0x8765432187654321 2017-01-01 [E] [expires: 2019-01-01]
  33 ```
  34
  35 The key ID is the hexadecimal number next to ```rsa4096/``` in the line
  36 starting with ```pub``` (not ```sub```). In this case the key ID is: ```0x1234567812345678```
  37
  38 In order to add your key to the list of keys which can read the ansible vault
  39 you first need to export the public part of your key using the following
  40 command:
  41
  42 ```
  43 # gpg2 --armor --export "<your key id>" > mykey.asc
  44 ```
  45
  46
  47
  48 Adding a key to the Vault
  49 -------------------------
  50
  51 Everybody who currently has access to the vault can add keys using the
  52 following command:
  53
  54 ```
  55 # gpg/add-keys.sh mykey.asc
  56 ```
  57
  58 This will add the new key to the keyring stored inside the repository and
  59 re-encrypt the secret to unlock the vault for all keys inside the keyring.
  60
  61
  62
  63 Removing a key from the Vault
  64 -----------------------------
  65
  66 Everybody who currently has access to the vault can remove keys using the
  67 following command:
  68
  69 ```
  70 # gpg/remove-keys.sh "<key-id>"
  71 ```
  72
  73 This will remove the key from the keyring stored inside the repository and
  74 re-encrypt the secret to unlock the vault for all remaining keys inside the
  75 keyring.
  76
  77 You can find out the key ID using the command:
  78
  79 ```
  80 # gpg/list-keys.sh
  81 ```
  82
  83 Here is an example output:
  84
  85 ```
  86 pub   rsa4096/0x1234567812345678 2017-01-01 [SC] [expires: 2019-01-01]
  87       Key fingerprint = 1234 5678 1234 5678 1234  5678 1234 5678 1234 5678
  88 uid                   [ unknown] Firstname Lastname <lastname@example.com>
  89 sub   rsa4096/0x8765432187654321 2017-01-01 [E] [expires: 2019-01-01]
  90 ```
  91
  92 The key ID is the hexadecimal number next to ```rsa4096/``` in the line
  93 starting with ```pub``` (not ```sub```). In this case the key ID is: ```0x1234567812345678```
  94
  95
  96
  97 Working with Vault files
  98 ------------------------
  99
 100  * create new vault:
 101    ```
 102    # ansible-vault create host_vars/foo/vault.yml
 103    ```
 104    This will open up an editor which allows you to add variables. Once you
 105    store and close the file the content is automatically encrypted.
 106
 107  * edit a vault file:
 108    ```
 109    # ansible-vault edit group_vars/foo/vault.yml
 110    ```
 111    This will open up an editor which allows you to add/remove/change variables.
 112    Once you store and close the file the content is automatically encrypted.
 113
 114  * show the contents of a vault file:
 115    ```
 116    # ansible-vault view secrets/foo.vault.yml
 117    ```
 118    This will automatically decrypt the file and print it's contents.