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

     1  User Guide
     2  ==========
     3  
     4  # Overview
     5  
     6  Suppose you have a VCS repository (i.e. a Git or Mercurial repo) and
     7  certain files contain secrets such as passwords or SSL private keys.
     8  Often people just store such files "and hope that nobody finds them in
     9  the repo". That's not safe.  Hope is not a strategy.
    10  
    11  With BlackBox, those files are stored encrypted using GPG. Access to
    12  the repo without also having the right GPG keys makes those files as worthless
    13  as random bits. As long as you keep your GPG keys safe, you don't
    14  have to worry about storing your VCS repo on an untrusted server or
    15  letting anyone clone the repo.
    16  
    17  Heck, even if you trust your server, now you don't have to trust the
    18  people that do backups of that server!
    19  
    20  Each person ("admin") of the system can decrypt all the files using
    21  their GPG key, which has its own passphrase.  The authorized GPG keys
    22  can decrypt any file.  This is better than systems that use one
    23  GPG key (and passphrase) that must be shared among a group of people.
    24  It is much better than having one passphrase for each file (I don't
    25  think anyone actually does that).
    26  
    27  Since any admin's GPG key can decrypt the files, if one person leaves
    28  the company, you don't have to communicate a new passphrase to everyone.
    29  Simply disable the one key that should no longer have access.
    30  The process for doing this is as easy as running 2 commands (1 to
    31  disable their key, 1 to re-encrypt all files.)  Obviously if they kept
    32  a copy of the repo (and their own passphrase) before leaving the
    33  company, they have access to the secrets. However, you should rotate
    34  those secrets anyway. ("rotate secrets" means changing the passwords,
    35  regenerating TLS certs, and so on).
    36  
    37  # Sample session:
    38  
    39  First we are going to list the files currently in the blackbox. In
    40  this case, it is an SSH private key.
    41  
    42  ```
    43  $ blackbox file list
    44  modules/log_management/files/id_rsa
    45  ```
    46  
    47  Excellent! Our coworkers have already registered a file with the
    48  system.  Let's decrypt it, edit it, and re-encrypt it.
    49  
    50  ```
    51  $ blackbox decrypt modules/log_management/files/id_rsa
    52  ========== DECRYPTING "modules/log_management/files/id_rsa"
    53  $ vi modules/log_management/files/id_rsa
    54  ```
    55  
    56  That was easy so far!
    57  
    58  When we encrypt it, Blackbox will not commit the changes, but it
    59  will give a hint that you should. It spells out the exact command you
    60  need to type and even proposes a commit message.
    61  
    62  ```
    63  $ blackbox encrypt modules/log_management/files/id_rsa
    64  ========== ENCRYPTING "modules/log_management/files/id_rsa"
    65  
    66  NEXT STEP: You need to manually check these in:
    67       git commit -m"ENCRYPTED modules/log_management/files/id_rsa" modules/log_management/files/id_rsa.gpg
    68  ```
    69  
    70  You can also use `blackbox edit <filename>` to decrypt a file, edit it
    71  (it will call `$EDITOR`) and re-encrypt it.
    72  
    73  
    74  Now let's register a new file with the blackbox system.
    75  `data/pass.yaml` is a small file that stores a very important
    76  password.  In this example, we had just stored the unecrypted
    77  password in our repo. That's bad.  Let's encrypt it.
    78  
    79  ```
    80  $ blackbox file add data/pass.yaml
    81  ========== SHREDDING ("/bin/rm", "-f"): "data/pass.yaml"
    82  
    83  NEXT STEP: You need to manually check these in:
    84       git commit -m"NEW FILES: data/pass.yaml" .gitignore keyrings/live/blackbox-files.txt modules/stacklb/pass.yaml modules/stacklb/pass.yaml.gpg
    85  ```
    86  
    87  Before we commit the change, let's do a `git status` to see what else
    88  has changed.
    89  
    90  ```
    91  $ git status
    92  On branch master
    93  Changes to be committed:
    94    (use "git restore --staged <file>..." to unstage)
    95  	modified:   .gitignore
    96  	modified:   keyrings/live/blackbox-files.txt
    97  	deleted:    modules/stacklb/pass.yaml
    98  	new file:   modules/stacklb/pass.yaml.gpg
    99  
   100  ```
   101  
   102  Notice that a number of files were modified:
   103  
   104  * `.gitignore`: This file is updated to include the plaintext
   105    filename, so that you don't accidentally add it to the repo in the
   106    future.
   107  * `.blackbox/blackbox-files.txt`: The list of files that are registered with the system.
   108  * `data/pass.yaml`: The file we encrypted is deleted from the repo.
   109  * `data/pass.yaml.gpg`: The encrypted file is added to the repo.
   110  
   111  Even though pass.yaml was deleted from the repo, it is still in the
   112  repo's history. Anyone with an old copy of the repo, or a new copy
   113  that knows how to view the repo's history, can see the secret
   114  password.  For that reason, you should change the password and
   115  re-encrypt the file.  This is an important point.  Blackbox is not
   116  magic and it doesn't have a "Men In Black"-style neuralizer that
   117  can make people forget the past.  If someone leaves a project, you
   118  have to change the old passwords, etc.
   119  
   120  Those are the basics.  Your next step might be:
   121  
   122  * TODO: How to enable Blackbox for a repo.
   123  * TODO: How to add yourself as an admin to a repo.
   124  * TODO: Complete list of [all blackbox commands](all-commands)