blackbox

BlackBox THIS PROJECT IS ABANDONED. DO NOT USE. DO NOT SUBMIT BUG REPORTS OR PRs. There are plenty of other, better, projects. A partial list is listed under "Alternatives" below. ======== Safely store secrets in a VCS repo (i.e. Git, Mercurial, Subversion or Perforce). These commands make it easy for you to Gnu Privacy Guard (GPG) encrypt specific files in a repo so they are "encrypted at rest" in your repository. However, the scripts make it easy to decrypt them when you need to view or edit them, and decrypt them for use in production. Originally written for Puppet, BlackBox now works with any Git or Mercurial repository. WARNING: The goal of this project is to be a simple wrapper around gpg so you and your coworkers don't have to remember its all those inscrutable and confusing flags. It is not intended to be a sophisticated encryption system that solves all problems or supports a large numbers of files. The ideal use-case is to keep secrets in a secure service such as Conjur, AWS KMS, Azure Key Vault or GCP KMS; then use Blackbox for safely storing the API keys needed to access that system. That way you are encrypting a single, tiny, file. Feature-requests for anything more will be rejected; do not expect or even request "enterprise features". If this disappoints you, please consider a competiting project such as https://www.agwa.name/projects/git-crypt A slide presentation (about an older release) is on SlideShare. Join our mailing list: https://groups.google.com/d/forum/blackbox-project What blackbox is NOT: Table of Contents BlackBox Table of Contents Overview Why is this important? Installation Instructions Commands Compatibility How is the encryption done? What does this look like to the typical user? Configuration Management How to use the secrets with Ansible? How to use the secrets with Puppet? Entire files Small strings File Management How to enroll a new file into the system? How to remove a file from the system? User Management How to indoctrinate a new user into the system? How to remove a user from the system? Note to the Web Of Trust Repo Management Enabling BlackBox For a Repo Set up automated users or “role accounts” Replacing expired keys Some common errors Using BlackBox on Windows Using BlackBox without a repo Some Subversion gotchas Using Blackbox when gpg2 is installed next to gpg How to submit bugs or ask questions? Developer Info Alternatives License 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. With BlackBox, those files are stored encrypted using GPG. Access to the VCS repo without also having the right GPG keys makes it worthless to have the files. As long as you keep your GPG keys safe, you don't have to worry about storing your VCS repo on an untrusted server. Heck, even if you trust your server, now you don't have to trust the people that do backups of that server, or the people that handle the backup tapes! Rather than one GPG passphrase for all the files, each person with access has their own GPG keys in the system. Any file can be decrypted by anyone with their GPG key. This way, if one person leaves the company, you don't have to communicate a new password to everyone with access. 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.) Automated processes often need access to all the decrypted files. This is easy too. For example, suppose Git is being used for Puppet files. The master needs access to the decrypted version of all the files. Simply set up a GPG key for the Puppet master (or the role account that pushes new files to the Puppet master) and have that user run blackbox_postdeploy after any files are updated. Getting started If you don't have a GPG key, set it up using instructions such as: Set up GPG key. Now you are ready to go. cd into a Git, Mercurial, Subversion or Perforce repository and run blackbox_initialize. If a file is to be encrypted, run blackbox_register_new_file and you are done. Add and remove keys with blackbox_addadmin and blackbox_removeadmin. To view and/or edit a file, run blackbox_edit; this will decrypt the file and open with whatever is specified by your $EDITOR environment variable. When you close the editor the file will automatically be encrypted again and the temporary plaintext file will be shredded. If you need to leave the file decrypted while you update you can use theblackbox_edit_start to decrypt the file and blackbox_edit_end when you want to "put it back in the box." Why is this important? OBVIOUSLY we don't want secret things like SSL private keys and passwords to be leaked. NOT SO OBVIOUSLY when we store "secrets" in a VCS repo like Git or Mercurial, suddenly we are less able to share our code with other people. Communication between subteams of an organization is hurt. You can't collaborate as well. Either you find yourself emailing individual files around (yuck!), making a special repo with just the files needed by your collaborators (yuck!!), or just deciding that collaboration isn't worth all that effort (yuck!!!). The ability to be open and transparent about our code, with the exception of a few specific files, is key to the kind of collaboration that DevOps and modern IT practitioners need to do. Installation Instructions The hard way (manual): Copy all the files in "bin" to your "bin". The hard way (automatic): make copy-install will copy the bin files into $PREFIX/bin, default is /usr/local (uninstall with make copy-uninstall). The symlinks way: make symlinks-install will make symlinks of the bin files into $PREFIX/bin, default is /usr/local (uninstall with make copy-uninstall) (useful when doing development) The MacPorts Way: sudo port insta