blackbox/docs/user-overview.md

User Guide

Overview

Suppose you have a VCS repository (i.e. a Git or Mercurial repo) and certain files contain secrets such as passwords or SSL private keys. Often people just store such files "and hope that nobody finds them in the repo". That's not safe. Hope is not a strategy.

With BlackBox, those files are stored encrypted using GPG. Access to the repo without also having the right GPG keys makes those files as worthless as random bits. As long as you keep your GPG keys safe, you don't have to worry about storing your VCS repo on an untrusted server or letting anyone clone the repo.

Heck, even if you trust your server, now you don't have to trust the people that do backups of that server!

Each person ("admin") of the system can decrypt all the files using their GPG key, which has its own passphrase. The authorized GPG keys can decrypt any file. This is better than systems that use one GPG key (and passphrase) that must be shared among a group of people. It is much better than having one passphrase for each file (I don't think anyone actually does that).

Since any admin's GPG key can decrypt the files, if one person leaves the company, you don't have to communicate a new passphrase to everyone. Simply disable the one key that should no longer have access. The process for doing this is as easy as running 2 commands (1 to disable their key, 1 to re-encrypt all files.) Obviously if they kept a copy of the repo (and their own passphrase) before leaving the company, they have access to the secrets. However, you should rotate those secrets anyway. ("rotate secrets" means changing the passwords, regenerating TLS certs, and so on).

Sample session:

First we are going to list the files currently in the blackbox. In this case, it is an SSH private key.

$ blackbox file list
modules/log_management/files/id_rsa

Excellent! Our coworkers have already registered a file with the system. Let's decrypt it, edit it, and re-encrypt it.

$ blackbox decrypt modules/log_management/files/id_rsa
========== DECRYPTING "modules/log_management/files/id_rsa"
$ vi modules/log_management/files/id_rsa

That was easy so far!

When we encrypt it, Blackbox will not commit the changes, but it will give a hint that you should. It spells out the exact command you need to type and even proposes a commit message.

$ blackbox encrypt modules/log_management/files/id_rsa
========== ENCRYPTING "modules/log_management/files/id_rsa"

NEXT STEP: You need to manually check these in:
     git commit -m"ENCRYPTED modules/log_management/files/id_rsa" modules/log_management/files/id_rsa.gpg

You can also use blackbox edit <filename> to decrypt a file, edit it (it will call $EDITOR) and re-encrypt it.

Now let's register a new file with the blackbox system. data/pass.yaml is a small file that stores a very important password. In this example, we had just stored the unecrypted password in our repo. That's bad. Let's encrypt it.

$ blackbox file add data/pass.yaml
========== SHREDDING ("/bin/rm", "-f"): "data/pass.yaml"

NEXT STEP: You need to manually check these in:
     git commit -m"NEW FILES: data/pass.yaml" .gitignore keyrings/live/blackbox-files.txt modules/stacklb/pass.yaml modules/stacklb/pass.yaml.gpg

Before we commit the change, let's do a git status to see what else has changed.

$ git status
On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   .gitignore
	modified:   keyrings/live/blackbox-files.txt
	deleted:    modules/stacklb/pass.yaml
	new file:   modules/stacklb/pass.yaml.gpg

Notice that a number of files were modified:

• .gitignore: This file is updated to include the plaintext filename, so that you don't accidentally add it to the repo in the future.
• .blackbox/blackbox-files.txt: The list of files that are registered with the system.
• data/pass.yaml: The file we encrypted is deleted from the repo.
• data/pass.yaml.gpg: The encrypted file is added to the repo.

Even though pass.yaml was deleted from the repo, it is still in the repo's history. Anyone with an old copy of the repo, or a new copy that knows how to view the repo's history, can see the secret password. For that reason, you should change the password and re-encrypt the file. This is an important point. Blackbox is not magic and it doesn't have a "Men In Black"-style neuralizer that can make people forget the past. If someone leaves a project, you have to change the old passwords, etc.

Those are the basics. Your next step might be:

• TODO: How to enable Blackbox for a repo.
• TODO: How to add yourself as an admin to a repo.
• TODO: Complete list of all blackbox commands