george/blackbox
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clarify .blackbox vs keyrings/live in README.md

Browse Source
This commit is contained in:
Tom Limoncelli
2018-06-15 09:22:05 -04:00
parent 07546c6205
commit 69c0360a99
1 changed files with 118 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
README.md
View File

@@ -39,7 +39,6 @@ Table of Contents
- [Alternatives](#alternatives)
- [License](#license)
Overview
========
@@ -108,7 +107,7 @@ BlackBox automatically determines which VCS you are using and does the right thi
- `hg` -- Mercurial
- `svn` -- SubVersion (Thanks, Ben Drasin!)
- `p4` -- Perforce
- none -- The files can be decrypted outside of a repo if the keyrings directory is intact
- none -- The files can be decrypted outside of a repo if the `.blackbox` directory is intact
- Operating system
- CentOS / RedHat
- MacOS X
@@ -170,7 +169,6 @@ Development:
- unknown (if you develop Blackbox under MinGW, please let us know if any additional packages are required to run `make test`)
How is the encryption done?
===========================
@@ -295,6 +293,8 @@ blackbox_deregister_file path/to/file.name.key
How to indoctrinate a new user into the system?
===============================================
FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
`.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.)
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.
@@ -348,7 +348,7 @@ Ask someone that already has access to re-encrypt the data files. This gives you
Pre-check: Verify the new keys look good.
```
$ gpg --homedir=.blackbox --list-keys
gpg --homedir=.blackbox --list-keys
```
For example, examine the key name (email address) to make sure it conforms to corporate standards.
@@ -392,16 +392,48 @@ When the command completes, you will be given a reminder to check in the change
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.
FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
```
gpg --homedir=.blackbox --list-keys
gpg --homedir=.blackbox --delete-key olduser@example.com
git commit -m'Cleaned olduser@example.com from keyring' .blackbox/*
```
FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
The key ring only has public keys. There are no secret keys to delete.
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.
Where is the configuration stored? .blackbox vs. keyrings/live
==============================================================
Blackbox stores its configuration data in the `.blackbox` subdirectory. Older
repos use `keyrings/live`. For backwards compatibility either will work.
All documentation refers to `.blackbox`.
You can convert an old repo by simply renaming the directory:
```
mv keyrings/live .blackbox
rmdir keyrings
```
There is no technical reason to convert old repos except that it is less
confusing to users.
This change was made in commit 60e782a0, release v1.20180615.
The details:
- First Blackbox checks `$BLACKBOXDATA`. If this environment variable is set, this is the directory that will be used. If it lists a directory that does not exist, Blackbox will print an error and exit.
- If `$BLACKBOXDATA` is not set: (which is the typical use case)
- Blackbox will first try `keyrings/live` and use it if it exists.
- Otherwise the default `.blackbox` will be used. If `.blackbox` does not exist, Blackbox will print an error and exit.
Enabling BlackBox For a Repo
============================
@@ -409,11 +441,13 @@ Overview:
To add "blackbox" to a git or mercurial repo, you'll need to do the following:
1. Run the initialize script. This adds a few files to your repo in a directory called "keyrings".
1. Run the initialize script. This adds a few files to your repo in a directory called ".blackbox".
2. For the first user, create a GPG key and add it to the key ring.
3. Encrypt the files you want to be "secret".
4. For any automated user (one that must be able to decrypt without a passphrase), create a GPG key and create a subkey with an empty passphrase.
FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
### Run the initialize script.
You'll want to include blackbox's "bin" directory in your PATH:
@@ -463,6 +497,8 @@ Set up automated users or "role accounts"
i.e. This is how a Puppet Master can have access to the unencrypted data.
FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
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.
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.
@@ -525,9 +561,9 @@ Command> save
Now securely export this directory to NEWMASTER:
```
$ gpg --homedir . --export -a svc_sadeploy >/tmp/NEWMASTER/pubkey.txt
$ tar cvf /tmp/keys.tar .
$ rsync -avP /tmp/keys.tar NEWMASTER:/tmp/.
gpg --homedir . --export -a svc_sadeploy >/tmp/NEWMASTER/pubkey.txt
tar cvf /tmp/keys.tar .
rsync -avP /tmp/keys.tar NEWMASTER:/tmp/.
```
On NEWMASTER, receive the new GnuPG config:
@@ -557,14 +593,14 @@ blackbox_addadmin $KEYNAME /tmp/NEWMASTER
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.
```
$ cd .blackbox
$ ls -l secring.gpg
cd .blackbox
ls -l secring.gpg
```
Commit the recent changes:
```
$ cd .blackbox
cd .blackbox
git commit -m"Adding key for KEYNAME" pubring.gpg trustdb.gpg blackbox-admins.txt
```
@@ -613,6 +649,8 @@ $ blackbox_edit_end modified_file.txt
--> Error: can't re-encrypt because a key has expired.
```
FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
You can also detect keys that are about to expire by issuing this command and manually reviewing the "expired:" dates:
gpg --homedir=.blackbox --list-keys
@@ -667,11 +705,13 @@ Any files that were temporarily copied in the first step so as to not be overwri
It's possible to tell Git to decrypt versions of the file before running them through `git diff` or `git log`. To achieve this do:
- Add the following to `.gitattributes` at the top of the git repository:
```
*.gpg diff=blackbox
```
- Add the following to `.git/config`:
```
[diff "blackbox"]
textconv = gpg --use-agent -q --batch --decrypt
@@ -688,10 +728,12 @@ Some common errors
`Error: can't re-encrypt because a key has expired.` -- A user's key has expired and can't be used to encrypt any more. Follow the [Replace expired keys](#replace-expired-keys) tip.
FYI: Your repo may use `keyrings/live` instead of `.blackbox`. See "Where is the configuration stored?"
Using Blackbox without a repo
=============================
If the files are copied out of a repo they can still be decrypted and edited. Obviously edits, changes to keys, and such will be lost if they are made outside the repo. Also note that commands are most likely to only work if run from the base directory (i.e. the parent to the keyrings directory).
If the files are copied out of a repo they can still be decrypted and edited. Obviously edits, changes to keys, and such will be lost if they are made outside the repo. Also note that commands are most likely to only work if run from the base directory (i.e. the parent to the .blackbox directory).
The following commands have been tested outside a repo: