Encryption for Git users.
Strongbox makes it easy to encrypt and decrypt files stored in Git, with
minimal divergence from a typical Git workflow. Once installed, Strongbox
enables normal use of commands such as git diff
etc. and all of the files
that should be encrypted in the repository remain decrypted on your working
copy.
It supports use of different keys per directory if wanted. It can cover as many or as few files as you wish based on .gitattributes
You can obtain a binary from https://github.com/uw-labs/strongbox/releases
Alternatively, assuming you have a working Go installation, you can install via the following command:
$ go install github.com/uw-labs/strongbox@v1.1.0
If you're on macOS or Linux and have Homebrew installed, getting Strongbox is as simple as running:
$ brew install uw-labs/tap/strongbox
Strongbox supports age and siv encryption. Age is the recommended option.
encryption | identity / keyring file | recipient / key file |
---|---|---|
age | .strongbox_identity | .strongbox_recipient |
siv | .strongbox_keyring | .strongbox-keyid |
If both identity / key files are present in the same directory,
.strongbox_identity
(age) will be preferred.
-
As a one time action, install the plugin by running
strongbox -git-config
. This will edit global Git config to enable Strongbox filter and diff configuration. -
In each repository you want to use Strongbox, create
.gitattributes
file containing the patterns to be managed by Strongbox.For example:
secrets/* filter=strongbox diff=strongbox
-
Generate a key to use for the encryption, for example:
strongbox -gen-identity my-key
This will generate a new age keypair and place it in
~/.strongbox_identity
. You can specify alternative location using-identity-file
flag or setting$HOME
envvar. -
Include
.strongbox_recipient
file in your repository (https://github.com/FiloSottile/age?tab=readme-ov-file#recipient-files). This can be in the same directory as the protected resource(s) or any parent directory. When searching for.strongbox_recipient
for a given resource, Strongbox will recurse up the directory structure until it finds the file. This allows using different keys for different subdirectories within a repository. -
If Strongbox identity file is stored in different location
-identity-file
can be used. iestrongbox [-identity-file <identity_file_path>] -gen-identity key-name
Strongbox uses clean and smudge filters to encrypt and decrypt files.
If you are cloning a project that uses Strongbox, you will need to have identity in your Strongbox identity file prior to cloning (checkout). Otherwise that filter will fail and not decrypt files on checkout.
If you already have the project locally and added identity, you can remove and checkout the files to force the filter:
rm <files> && git checkout -- <files>
Following a git add
, you can verify the file is encrypted in the index:
$ git show :/path/to/file
Verify a file is encrypted in the commit:
$ git show HEAD:/path/to/file
What you should see is a Strongbox encrypted resource, and this is what would be pushed to the remote.
Compare an entire branch (as it would appear on the remote) to master:
$ git diff-index -p master
To rotate keys, update the .strongbox_recipient
with the new value, then
touch
all files/directories covered by .gitattributes
. All affected files
should now show up as "modified".
Strongbox uses age and SIV-AES as defined in rfc5297.
Run integration tests:
$ make test
Following commands can be used to decrypt files outside of the Git flow:
# decrypt using default keyring file `$HOME/.strongbox_keyring`
strongbox -decrypt -recursive <path>
# decrypt using `keyring_file_path`
strongbox -keyring <keyring_file_path> -decrypt -recursive <path>
# decrypt using private key `<key>`
strongbox -key <key> -decrypt -recursive <path>
# decrypt single file with given key
strongbox -decrypt -key <key>
Given a .strongbox-keyid
in the root of the repository and an encrypted file
in the same directory,and alphabetically it comes before the key-id file.
Git checks out files alphanumerically, so if the strongboxed file is being
checked out before the .strongbox-keyid
is present on disk, strongbox will
fail to find the decryption key.
Order of files being cloned is dictated by the index.
- Clone repository, let the descryption fail. Delete encrypted files and do
git checkout
on the deleted files. - Move affected files down to a subdirectory from
.strongbox-keyid
file