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

     1  User Management
     2  ===============
     3  
     4  
     5  # Who are the current admins?
     6  
     7  ```
     8  blackbox admin list
     9  ```
    10  
    11  
    12  # Add a new user (admin)
    13  
    14  FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
    15  
    16  `.blackbox/blackbox-admins.txt` is a file that lists which users are able to decrypt files. (More pedantically, it is a list of the GnuPG key names that the file is encrypted for.)
    17  
    18  To join the list of people that can edit the file requires three steps; You create a GPG key and add it to the key ring. Then, someone that already has access adds you to the system. Lastly, you should test your access.
    19  
    20  ## Step 1: NEWPERSON creates a GPG key pair on a secure machine and add to public keychain.
    21  
    22  If you don't already have a GPG key, here's how to generate one:
    23  
    24  ```
    25  gpg --gen-key
    26  ```
    27  
    28  WARNING: New versions of GPG generate keys which are not understood by
    29  old versions of GPG.  If you generate a key with a new version of GPG,
    30  this will cause problems for users of older versions of GPG.
    31  Therefore it is recommended that you either assure that everyone using
    32  Blackbox have the exact same version of GPG, or generate GPG keys
    33  using a version of GPG as old as the oldest version of GPG used by
    34  everyone using Blackbox.
    35  
    36  Pick defaults for encryption settings, 0 expiration. Pick a VERY GOOD
    37  passphrase. Store a backup of the private key someplace secure. For
    38  example, keep the backup copy on a USB drive that is locked in safe.
    39  Or, at least put it on a secure machine with little or no internet
    40  access, full-disk-encryption, etc. Your employer probably has rules
    41  about how to store such things.
    42  
    43  FYI: If generating the key is slow, this is usually because the system
    44  isn't generating enough entropy.  Tip: Open another window on that
    45  machine and run this command: `ls -R /`
    46  
    47  Now that you have a GPG key, add yourself as an admin:
    48  
    49  ```
    50  blackbox admin add KEYNAME
    51  ```
    52  
    53  ...where "KEYNAME" is the email address listed in the gpg key you created previously. For example:
    54  
    55  ```
    56  blackbox admin add tal@example.com
    57  ```
    58  
    59  When the command completes successfully, instructions on how to commit these changes will be output. Run the command as given to commit the changes. It will look like this:
    60  
    61  ```
    62  git commit -m'NEW ADMIN: tal@example.com' .blackbox/pubring.gpg .blackbox/trustdb.gpg .blackbox/blackbox-admins.txt
    63  ```
    64  
    65  
    66  Then push it to the repo:
    67  
    68  ```
    69  git push
    70  
    71  or
    72  
    73  ht push
    74  
    75  (or whatever is appropriate)
    76  ```
    77  
    78  NOTE: Creating a Role Account? If you are adding the pubring.gpg of a role account, you can specify the directory where the pubring.gpg file can be found as a 2nd parameter: `blackbox admin add puppetmaster@puppet-master-1.example.com /path/to/the/dir`
    79  
    80  ## Step 2: AN EXISTING ADMIN accepts you into the system.
    81  
    82  Ask someone that already has access to re-encrypt the data files. This
    83  gives you access. They simply decrypt and re-encrypt the data without
    84  making any changes.
    85  
    86  Pre-check: Verify the new keys look good.
    87  
    88  ```
    89  git pull    # Or whatever is required for your system
    90  gpg --homedir=.blackbox --list-keys
    91  ```
    92  
    93  For example, examine the key name (email address) to make sure it conforms to corporate standards.
    94  
    95  Import the keychain into your personal keychain and reencrypt:
    96  
    97  ```
    98  gpg --import .blackbox/pubring.gpg
    99  blackbox reencrypt --all shred
   100  ```
   101  
   102  Push the re-encrypted files:
   103  
   104  ```
   105  git commit -a
   106  git push
   107  
   108  or
   109  
   110  hg commit
   111  hg push
   112  ```
   113  
   114  ### Step 3: NEWPERSON tests.
   115  
   116  Make sure you can decrypt a file. (Suggestion: Keep a dummy file in
   117  VCS just for new people to practice on.)
   118  
   119  
   120  # Remove a user
   121  
   122  Simply run `blackbox admin remove` with their keyname then re-encrypt:
   123  
   124  Example:
   125  
   126  ```
   127  blackbox admin remove olduser@example.com
   128  blackbox reencrypt --all shred
   129  ```
   130  
   131  When the command completes, you will be given a reminder to check in the change and push it.
   132  
   133  Note that their keys will still be in the key ring, but they will go unused. If you'd like to clean up the keyring, use the normal GPG commands and check in the file.
   134  
   135  FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
   136  
   137  ```
   138  gpg --homedir=.blackbox --list-keys
   139  gpg --homedir=.blackbox --delete-key olduser@example.com
   140  git commit -m'Cleaned olduser@example.com from keyring'  .blackbox/*
   141  ```
   142  
   143  FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
   144  
   145  The key ring only has public keys. There are no secret keys to delete.
   146  
   147  Remember that this person did have access to all the secrets at one time. They could have made a copy. Therefore, to be completely secure, you should change all passwords, generate new SSL keys, and so on just like when anyone that had privileged access leaves an organization.
   148