github.com/StackExchange/blackbox/v2@v2.0.1-0.20220331193400-d84e904973ab/docs/role-accounts.md (about)

     1  Set up automated users or "role accounts"
     2  =========================================
     3  
     4  TODO(tlim): I think this is overly complex. With GnuPG 2.2 and later,
     5  you can use `--password '' --quick-generate-key userid` and you are
     6  done. No need for subkeys.  Maybe rework this?
     7  
     8  With role accounts, you have an automated system that needs to be able
     9  to decrypt secrets without a password. This means the security of your
    10  repo is based on how locked down the automation system is. This
    11  is risky, so be careful.
    12  
    13  
    14  i.e. This is how a Puppet Master can have access to the unencrypted data.
    15  
    16  FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
    17  
    18  An automated user (a "role account") is one that that must be able to decrypt without a passphrase. In general you'll want to do this for the user that pulls the files from the repo to the master. This may be automated with Jenkins CI or other CI system.
    19  
    20  GPG keys have to have a passphrase. However, passphrases are optional on subkeys. Therefore, we will create a key with a passphrase then create a subkey without a passphrase. Since the subkey is very powerful, it should be created on a very secure machine.
    21  
    22  There's another catch. The role account probably can't check files into Git/Mercurial. It probably only has read-only access to the repo. That's a good security policy. This means that the role account can't be used to upload the subkey public bits into the repo.
    23  
    24  Therefore, we will create the key/subkey on a secure machine as yourself. From there we can commit the public portions into the repo. Also from this account we will export the parts that the role account needs, copy them to where the role account can access them, and import them as the role account.
    25  
    26  ProTip: If asked to generate entropy, consider running this on the same machine in another window: `sudo dd if=/dev/sda of=/dev/null`
    27  
    28  For the rest of this doc, you'll need to make the following substitutions:
    29  
    30  - ROLEUSER: svc_deployacct or whatever your role account's name is.
    31  - NEWMASTER: the machine this role account exists on.
    32  - SECUREHOST: The machine you use to create the keys.
    33  
    34  NOTE: This should be more automated/scripted. Patches welcome.
    35  
    36  On SECUREHOST, create the puppet master's keys:
    37  
    38  ```
    39  $ mkdir /tmp/NEWMASTER
    40  $ cd /tmp/NEWMASTER
    41  $ gpg --homedir . --gen-key
    42  Your selection?
    43     (1) RSA and RSA (default)
    44  What keysize do you want? (2048) DEFAULT
    45  Key is valid for? (0) DEFAULT
    46  
    47  # Real name: Puppet CI Deploy Account
    48  # Email address: svc_deployacct@hostname.domain.name
    49  ```
    50  
    51  NOTE: Rather than a real email address, use the username@FQDN of the host the key will be used on. If you use this role account on many machines, each should have its own key. By using the FQDN of the host, you will be able to know which key is which. In this doc, we'll refer to username@FQDN as $KEYNAME
    52  
    53  Save the passphrase somewhere safe!
    54  
    55  Create a sub-key that has no password:
    56  
    57  ```
    58  $ gpg --homedir . --edit-key svc_deployacct
    59  gpg> addkey
    60  (enter passphrase)
    61    Please select what kind of key you want:
    62     (3) DSA (sign only)
    63     (4) RSA (sign only)
    64     (5) Elgamal (encrypt only)
    65     (6) RSA (encrypt only)
    66  Your selection? 6
    67  What keysize do you want? (2048)
    68  Key is valid for? (0)
    69  Command> key 2
    70  (the new subkey has a "*" next to it)
    71  Command> passwd
    72  (enter the main key's passphrase)
    73  (enter an empty passphrase for the subkey... confirm you want to do this)
    74  Command> save
    75  ```
    76  
    77  Now securely export this directory to NEWMASTER:
    78  
    79  ```
    80  gpg --homedir . --export -a svc_sadeploy >/tmp/NEWMASTER/pubkey.txt
    81  tar cvf /tmp/keys.tar .
    82  rsync -avP /tmp/keys.tar NEWMASTER:/tmp/.
    83  ```
    84  
    85  On NEWMASTER, receive the new GnuPG config:
    86  
    87  ```
    88  sudo -u svc_deployacct bash
    89  mkdir -m 0700 -p ~/.gnupg
    90  cd ~/.gnupg && tar xpvf /tmp/keys.tar
    91  ```
    92  
    93  <!---
    94  Back on SECUREHOST, import the pubkey into the repository.
    95  
    96  ```
    97  $ cd .blackbox
    98  $ gpg --homedir . --import /tmp/NEWMASTER/pubkey.txt
    99  ```
   100  -->
   101  
   102  Back on SECUREHOST, add the new email address to .blackbox/blackbox-admins.txt:
   103  
   104  ```
   105  cd /path/to/the/repo
   106  blackbox_addadmin $KEYNAME /tmp/NEWMASTER
   107  ```
   108  
   109  Verify that secring.gpg is a zero-length file. If it isn't, you have somehow added a private key to the keyring. Start over.
   110  
   111  ```
   112  cd .blackbox
   113  ls -l secring.gpg
   114  ```
   115  
   116  Commit the recent changes:
   117  
   118  ```
   119  cd .blackbox
   120  git commit -m"Adding key for KEYNAME" pubring.gpg trustdb.gpg blackbox-admins.txt
   121  ```
   122  
   123  Regenerate all encrypted files with the new key:
   124  
   125  ```
   126  blackbox_update_all_files
   127  git status
   128  git commit -m"updated encryption" -a
   129  git push
   130  ```
   131  
   132  On NEWMASTER, import the keys and decrypt the files:
   133  
   134  ```
   135  sudo -u svc_sadeploy bash   # Become the role account.
   136  gpg --import /etc/puppet/.blackbox/pubring.gpg
   137  export PATH=$PATH:/path/to/blackbox/bin
   138  blackbox_postdeploy
   139  sudo -u puppet cat /etc/puppet/hieradata/blackbox.yaml # or any encrypted file.
   140  ```
   141  
   142  ProTip: If you get "gpg: decryption failed: No secret key" then you forgot to re-encrypt blackbox.yaml with the new key.
   143  
   144  On SECUREHOST, securely delete your files:
   145  
   146  ```
   147  cd /tmp/NEWMASTER
   148  # On machines with the "shred" command:
   149  shred -u /tmp/keys.tar
   150  find . -type f -print0 | xargs -0 shred -u
   151  # All else:
   152  rm -rf /tmp/NEWMASTER
   153  ```
   154  
   155  Also shred any other temporary files you may have made.
   156  
   157  
   158