# Use case
You need a secure way to store your secrets in your git repository (passwords, credentials, AWS Secret Access key, Wordpress wp-config.php file).
Storing this information in plain-text in your git repository might later be a problem if you want to publish your project on github, sell your project without revealing your own credentials, backup your project knowing that your passwords / private keys are safe, etc.
I recommend blackbox developed by StackExchange: it's a powerful and easy to use.
It works well with both personal repository and repositories with many contributors (it handles different keys for each contributor if necessary).
It supports git, hg, svn, p4 or vanilla (outside of a repository).
Once it's setup, you will be able to securely store a secret on your repository with a simple command line:
# Step-by-step How-to
Here is a step-by-step guide to create a secret on a git repository (we suppose that your git repository already exists).
# Step 1: Create a gpg key (if you don't already have one)
# Step 1a: Create a gpp key
$ gpg --gen-key
- Kind of key: RSA and RSA
- Keysize: 4096
- Expire: 0
- Real name:
your_name <your_email@your_host.com>(please personalize this one)
- Secure passphrase: Use a strong passphrase, usually with at least 8 characters including some special characters (like
Generating a gpg key might take quite some time (you might get a message like
Not enough random bytes available),
gpg will run in the background waiting for more "random data" to be available so it can generate a stronger key.
This step generally takes a few minutes, but it might take from a few seconds to a few hours depending on how much you use your computer (the more you use it, the faster it goes). You don't need to babysit the gpg process, just browse the Internet, play some game, start a few applications, etc... the key will continue to be generated by itself.
More information: GitHub - Generating a new GPG key
# Step 1b: Backup your gpg private key
Once it's done, I recommend that you backup your gpg key. It will be useful to continue to access your encrypted files if you lose your key.
Either backup these two files:
Or backup the result from these two commands:
- Public key:
gpg --export --armor
- Private key:
gpg --export-secret-keys --armor
gpg to export the keys using ASCII text instead of a binary format)
Keep the backup of your private key in a safe place! (consider it like one of your password)
# Step 2: Install blackbox
You have different installation instructions on their github page.
Here is the fastest one:
$ mkdir ~/Applications $ cd ~/Applications $ git clone firstname.lastname@example.org:StackExchange/blackbox.git $ cd blackbox $ sudo make manual-install
Now you can type
hash -r or restart your terminal to have access to the installed binaries.
# Step 3: Initialize blackbox on your git repo
Add your gpg key to the admins (replace your_email@your_host.com by the email you used when creating your key):
$ blackbox_addadmin your_email@your_host.com
Alternatively can use your gpg key id (find it by running
gpg --list-keys, if it displays
pub 4096R/0A1F3042 2016-12-15, use
# Step 4: Encrypt a file
If you want to encrypt an existing file (wp-config.php for example), here is how you do (we suppose that this file already exists in the folder you are in):
$ blackbox_register_new_file wp-config.php
This command will encrypt the file, add the encrypted
wp-config.php.gpg file to the repository and add the plain-text
wp-config.php file to
.gitignore so it's not added to the repository by mistake in the future.
You'll still need to
git commit and
git push the changes.
(In comparison, the command to edit an already encrypted file is
# Step 5: Reveal all the encrypted files
The plain-text version of a file is deleted after being encrypted, if you want to use it you'll need to reveal your encrypted files:
You can also decrypt individual files, edit encrypted files, manage permissions, etc.
Please check the blackbox github page for more information!