ansible/README_vault.md

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