git-secret

Thu, 27 Oct 2022 17:51:47 +0000

git-secret - bash tool to store private data inside a git repo.

Usage: Setting up git-secret in a repository

These steps cover the basic process of using git-secret to specify users and files that will interact with git-secret, and to encrypt and decrypt secrets.

Before starting, make sure you have created a gpg RSA key-pair: which are a public key and a secret key pair, identified by your email address and stored with your gpg configuration. Generally this gpg configuration and keys will be stored somewhere in your home directory.
Begin with an existing or new git repository.
Initialize the git-secret repository by running git secret init. The .gitsecret/ folder will be created, with subdirectories keys/ and paths/, .gitsecret/keys/random_seed will be added to .gitignore, and .gitignore will be configured to not ignore .secret files.

Note all the contents of the .gitsecret/ folder should be checked in, /except/ the random_seed file. This also means that of all the files in .gitsecret/, only the random_seed file should be mentioned in your .gitignore file.

Add the first user to the git-secret repo keyring by running git secret tell your@email.id.
Now it’s time to add files you wish to encrypt inside the git-secret repository. This can be done by running git secret add <filenames...> command, which will also (as of 0.2.6) add entries to .gitignore, stopping those files from being added or committed to the repo unencrypted.
Then run git secret hide to encrypt the files you added with git secret add. The files will be encrypted with the public keys in your git-secret repo’s keyring, each corresponding to a user’s email that you used with tell.

After using git secret hide to encrypt your data, it is safe to commit your changes. NOTE: It’s recommended to add the git secret hide command to your pre-commit hook, so you won’t miss any changes.

Later you can decrypt files with the git secret reveal command, or print their contents to stdout with the git secret cat command. If you used a password on your GPG key (always recommended), it will ask you for your password. And you’re done!

Usage: Adding someone to a repository using git-secret

Get their gpg public-key. You won’t need their secret key. They can export their public key for you using a command like: gpg --armor --export their@email.id > public_key.txt # --armor here makes it ascii
Import this key into your gpg keyring (in ~/.gnupg or similar) by running gpg --import public_key.txt
Now add this person to your secrets repo by running git secret tell their@email.id (this will be the email address associated with their public key)
Now remove the other user’s public key from your personal keyring with gpg --delete-keys their@email.id
The newly added user cannot yet read the encrypted files. Now, re-encrypt the files using git secret reveal; git secret hide -d, and then commit and push the newly encrypted files. (The -d options deletes the unencrypted file after re-encrypting it). Now the newly added user will be able to decrypt the files in the repo using git-secret reveal.

Note that when you first add a user to a git-secret repo, they will not be able to decrypt existing files until another user re-encrypts the files with the new keyring.

If you do not want unexpected keys added, you can configure some server-side security policy with the pre-receive hook.

Using gpg

You can follow a quick gpg tutorial at devdungeon. Here are the most useful commands to get started:

To generate a RSA key-pair, run:

gpg --gen-key

To export your public key, run:

gpg --armor --export your.email@address.com > public-key.gpg

To import the public key of someone else (to share the secret with them for instance), run:

gpg --import public-key.gpg

To make sure you get the original public keys of the indicated persons, be sure to use a secure channel to transfer it, or use a service you trust, preferably one that uses encryption such as Keybase, to retrieve their public key. Otherwise you could grant the wrong person access to your secrets by mistake!

Using git-secret for Continuous Integration / Continuous Deployment (CI/CD)

When using git-secret for CI/CD, you get the benefit that any deployment is necessarily done with the correct configuration, since it is collocated with the changes in your code.

One way of doing it is the following:

create a gpg key for your CI/CD environment. You can chose any name and email address you want: for instance MyApp Example <myapp@example.com> if your app is called MyApp and your CI/CD provider is Example. It is easier not to define a passphrase for that key. However, if defining a passphrase is unavoidable, use a unique passphrase for the private key.
run gpg --armor --export-secret-key myapp@example.com to get your private key value
Create an env var on your CI/CD server GPG_PRIVATE_KEY and assign it the private key value. If a passphrase has been setup for the private key, create another env var on the CI/CD server GPG_PASSPHRASE and assign it the passphrase of the private key.
Then write your Continuous Deployment build script. For instance:

# As the first step: install git-secret,
# see: https://git-secret.io/installation

# Create private key file
echo "$GPG_PRIVATE_KEY" > ./private_key.gpg
# Import private key and avoid the "Inappropriate ioctl for device" error
gpg --batch --yes --pinentry-mode loopback --import private_key.gpg
# Reveal secrets without user interaction and with passphrase. If no passphrase
# is created for the key, remove `-p $GPG_PASSPHRASE`
git secret reveal -p "$GPG_PASSPHRASE"
# carry on with your build script, secret files are available ...

Note: your CI/CD might not allow you to create a multiline value. In that case, you can export it on one line with

gpg --armor --export-secret-key myapp@example.com | tr '\n' ','

You can then create your private key file with:

echo "$GPG_PRIVATE_KEY" | tr ',' '\n' > ./private_key.gpg

Also note: the gpg version on the CI/CD server MUST INTEROPERATE with the one used locally. Otherwise, gpg decryption can fail, which leads to git secret reveal reporting cannot find decrypted version of file error. The best way to ensure this is to use the same version of gnupg on different systems.

Environment Variables and Configuration

You can configure the version of gpg used, or the extension your encrypted files use, to suit your workflow better. To do so, just set the required variable to the value you need. This can be done in your shell environment file or with each git-secret command. See below, or the man page of git-secret for an explanation of the environment variables git-secret uses.

The settings available to be changed are:

$SECRETS_VERBOSE - sets the verbose flag to on for all git-secret commands; is identical to using -v on each command that supports it.
$SECRETS_GPG_COMMAND - sets the gpg alternatives, defaults to gpg. It can be changed to gpg, gpg2, pgp, /usr/local/gpg or any other value. After doing so rerun the tests to be sure that it won’t break anything. Tested with gpg and gpg2.
$SECRETS_GPG_ARMOR - sets the gpg --armor mode. Can be set to 1 to store secrets file as text. By default is 0 and store files as binaries.
$SECRETS_EXTENSION - sets the secret files extension, defaults to .secret. It can be changed to any valid file extension.
$SECRETS_DIR - sets the directory where git-secret stores its files, defaults to .gitsecret. It can be changed to any valid directory name.
$SECRETS_PINENTRY - allows user to specify a setting for gpg’s --pinentry option. See gpg docs for details about gpg’s --pinentry option.

The `.gitsecret` folder (can be overridden with `SECRETS_DIR`)

This folder contains information about the files encrypted by git-secret, and about which public/private key sets can access the encrypted data.

You can change the name of this directory using the SECRETS_DIR environment variable.

Use the various git-secret commands to manipulate the files in .gitsecret, you should not change the data in these files directly.

Exactly which files exist in the .gitsecret folder and what their contents are vary slightly across different versions of gpg. Also, some versions of gpg might not work well with keyrings created or modified with newer versions of gpg. Thus it is best to use git-secret with the same version of gpg being used by all users. This can be forced by installing matching versions of gpg and using SECRETS_GPG_COMMAND environment variable.

For example, there is an issue between gpg version 2.1.20 and later versions which can cause problems reading and writing keyring files between systems (this shows up in errors like ‘gpg: skipped packet of type 12 in keybox’).

This is not the only issue it is possible to encounter sharing files between different versions of gpg. Generally you are most likely to encounter issues between gpg versions if you use git-secret tell or git-secret removeperson to modify your repo’s git-secret keyring using a newer version of gpg, and then try to operate on that keyring using an older version of gpg.

The git-secret internal data is separated into two directories:

`.gitsecret/paths`

This directory currently contains only the file mapping.cfg, which lists all the files git-secret will consider secret. In other words, the path mappings: what files are tracked to be hidden and revealed.

All other internal data used by git-secret is stored in the directory:

`.gitsecret/keys`

This directory contains data used by git-secret and gpg to encrypt files to be accessed by the permitted users.

In particular, this directory contains a gnupg keyring with public keys for the emails used with tell.

This is the keyring used to encrypt files with git-secret-hide.

git-secret-reveal and git-secret-cat, which decrypt secrets, instead use the user’s private keys (which probably reside somewhere like ~/.gnupg/). Note that user’s private keys, needed for decryption, are not in the .gitsecret/keys directory.

Generally speaking, all the files in this directory except random_seed should be checked into your repo. By default, git secret init will add the file .gitsecret/keys/random_seed to your .gitignore file.

Again, you can change the name of this directory using the SECRETS_DIR environment variable.

git-secret-whoknows

Thu, 27 Oct 2022 17:51:47 +0000

git-secret-whoknows - print email for each key in the keyring.

SYNOPSIS

git secret whoknows

DESCRIPTION

git-secret-whoknows - print email addresses allowed to access the secrets in this repo.

OPTIONS

-l  - 'long' output, shows key expiration dates.
-h  - shows this help.

MANUAL

Run man git-secret-whoknows to see this document.

git-secret-usage

Thu, 27 Oct 2022 17:51:47 +0000

git-secret-usage - prints all the available commands.

SYNOPSIS

git secret usage

DESCRIPTION

git-secret-usage - prints all the available git-secret commands.

OPTIONS

-h  - shows this help.

MANUAL

Run man git-secret-usage to see this document.

git-secret-tell

Thu, 27 Oct 2022 17:51:47 +0000

git-secret-tell - adds person who can access private data.

SYNOPSIS

git secret tell [-m] [-d dir] [emails]...

DESCRIPTION

git-secret tell - adds user(s) to the list of those able to encrypt/decrypt secrets.

This lets the specified user encrypt new files, but will not immediately be able to decrypt existing files, which were encrypted without their key. Files should be re-encrypted with the new keyring by someone who already has access in order for the new user to be able to decrypt the files.

git-secret tell works only with email addresses, and will exit with an error if you have multiple keys in your keyring with specified email addresses, or if one of the specified emails is already associated with a key in the git-secret repo’s keyring.

Under the hood, git-secret-tell searches in the current user’s gnupg keyring for public key(s) of passed email(s), then imports the corresponding public key(s) into your git-secret repo’s keyring.

Versions of git-secret tell after 0.3.2 will warn about keys that are expired, revoked, or otherwise invalid. It will also warn if multiple keys are found for a single email address.

Do not manually import secret keys into git-secret. It won’t work with imported secret keys anyway.

For more details about how git-secret uses public and private keys, see the documentation for git-secret-hide and git-secret-reveal.

OPTIONS

-m  - uses your current `git config user.email` setting as an identifier for the key.
-d  - specifies `--homedir` option for `gpg`, basically use this option if your store your keys in a custom location.
-h  - shows help.

MANUAL

Run man git-secret-tell to see this document.

git-secret-reveal

Thu, 27 Oct 2022 17:51:47 +0000

git-secret-reveal - decrypts all added files.

SYNOPSIS

git secret reveal [-f] [-F] [-P] [-v] [-d dir] [-p password] [pathspec]...

DESCRIPTION

git-secret-reveal - decrypts passed files, or all files considered secret by git-secret.

Under the hood, reveal uses the gpg --decrypt command and your private key (typically from your personal keyring in your home directory) to decrypt files.

Therefore, for this operation to succeed, your personal keyring must contain a private key matching one of the public keys which were used to encrypt the secrets – i.e., one of the public keys in your repo’s git-secret keyring when the file was encrypted.

OPTIONS

-f  - forces gpg to overwrite existing files without prompt.
-F  - forces reveal to continue even if a file fails to decrypt.
-d  - specifies `--homedir` option for the `gpg`, basically use this option if you store your keys in a custom location.
-v  - verbose, shows extra information.
-p  - specifies password for noinput mode, adds `--passphrase` option for `gpg`.
-P  - preserve permissions of encrypted file in unencrypted file.
-h  - shows help.

ENV VARIABLES

SECRETS_GPG_COMMAND changes the default gpg command to anything else
SECRETS_GPG_ARMOR is a boolean to enable --armor mode to store secrets in text format over binary
SECRETS_DIR changes the default .gitsecret/ folder to another name as documented at git-secret(7)
SECRETS_EXTENSION changes the default .secret file extension
SECRETS_VERBOSE changes the output verbosity as documented at git-secret(7)
SECRETS_PINENTRY changes the gpg --pinentry mode as documented at git-secret(7)

MANUAL

Run man git-secret-reveal to see this document.

git-secret-removeperson

Thu, 27 Oct 2022 17:51:47 +0000

git-secret-removeperson - removes user’s public key from repo keyring.

SYNOPSIS

git secret removeperson <emails>...

DESCRIPTION

git-secret-removeperson - removes public keys for passed email addresses from repo’s git-secret keyring.

This command is used to begin the process of disallowing a user from encrypting and decrypting secrets with git-secret.

If you remove a user’s access with git-secret-removeperson, and then run git-secret-reveal and git-secret-hide -r, that user will no longer be able user to decrypt the hidden files.

OPTIONS

-h  - shows this help.

MANUAL

Run man git-secret-removeperson to see this document.

git-secret-remove

Thu, 27 Oct 2022 17:51:47 +0000

git-secret-remove - removes files from index.

SYNOPSIS

git secret remove [-c] <pathspec>...

DESCRIPTION

git-secret-remove - stops files from being tracked by git-secret.

This deletes filenames from .gitsecret/paths/mapping.cfg, which stops these files from being tracked by git-secret, and from being encrypted to, or decrypted from, .secret encrypted versions.

There’s also a -c option to delete existing encrypted versions of the files provided.

Note unlike add, which automatically add pathnames to .gitignore, remove does not delete pathnames from .gitignore.

(See git-secret(7) for information about renaming the .gitsecret folder using the SECRETS_DIR environment variable.

OPTIONS

-c  - deletes existing real encrypted files.
-h  - shows help.

MANUAL

Run man git-secret-remove to see this document.

git-secret-list

Thu, 27 Oct 2022 17:51:47 +0000

git-secret-list - prints all the added files.

SYNOPSIS

git secret list

DESCRIPTION

git-secret-list - print the files currently considered secret in this repo.

Shows tracked files from .gitsecret/paths/mapping.cfg.

(See git-secret(7) for information about renaming the .gitsecret folder using the SECRETS_DIR environment variable.

OPTIONS

-h  - shows this help.

MANUAL

Run man git-secret-list to see this document.

git-secret-init

Thu, 27 Oct 2022 17:51:47 +0000

git-secret-init - initializes git-secret repository.

SYNOPSIS

git secret init

DESCRIPTION

git-secret-init - initializes a git-secret repo by setting up a .gitsecret directory.

git-secret-init should be run inside a git repo, to create the .gitsecret directory and initialize the repo for git-secret. Until a repository is initialized with git secret init, all other git-secret commands are unavailable.

If a .gitsecret directory already exists, git-secret-init exits without making any changes. Otherwise,

.gitignore is modified to ignore git-secret’s random_seed_file, and to not ignore .secret files,
a .gitsecret directory is created with the sub-directories /keys and /paths,
The .gitsecret/keys subdirectory permission is set to 700 to make gnupg happy.

See git-secret(7) for information about renaming the .gitsecret folder with the SECRETS_DIR environment variable, and changing the extension git-secret uses for secret files with the SECRETS_EXTENSION environment variable.

OPTIONS

-h  - shows this help.

MANUAL

Run man git-secret-init to see this document.

git-secret-hide

Thu, 27 Oct 2022 17:51:47 +0000

git-secret-hide - encrypts all added files with repo keyring.

SYNOPSIS

git secret hide [-c] [-F] [-P] [-v] [-d] [-m]

DESCRIPTION

git-secret-hide - writes an encrypted version of each file added by git-secret-add command.

Then anyone enabled via git secret tell can decrypt these files.

Under the hood, git-secret uses the keyring of public keys in .gitsecret/keys to encrypt files, encrypted versions are typically called filename.txt.secret.

Later permitted users can use their secret key (typically from their home directory) to decrypt files.

It is recommended to encrypt (or re-encrypt) all the files in a git-secret repo each time git secret hide is run.
Otherwise the keyring (the one stored in .gitsecret/keys/*.gpg), may have changed since the last time the files were encrypted, and it’s possible to create a state where the users in the output of git secret whoknows may not be able to decrypt the some files in the repo, or may be able decrypt files they’re not supposed to be able to.

In other words, unless you re-encrypt all the files in a repo each time you hide any, it’s possible to make it so some files can no longer be decrypted by users who should be (and would appear) able to decrypt them, and vice-versa.

If you know what you are doing and wish to encrypt or re-encrypt only a subset of the files even after reading the above paragraphs, you can use the -F or -m options. The -F option forces git secret hide to skip any hidden files where the unencrypted versions aren’t present. The -m option skips any hidden files that have not be been modified since the last time they were encrypted.

OPTIONS

-v  - verbose, shows extra information.
-c  - deletes encrypted files before creating new ones.
-F  - forces hide to continue if a file to encrypt is missing.
-P  - preserve permissions of unencrypted file in encrypted file.
-d  - deletes unencrypted files after encryption.
-m  - encrypt files only when modified.
-h  - shows help.

ENV VARIABLES

SECRETS_GPG_COMMAND changes the default gpg command to anything else
SECRETS_GPG_ARMOR is a boolean to enable --armor mode to store secrets in text format over binary
SECRETS_DIR changes the default .gitsecret/ folder to another name as documented at git-secret(7)
SECRETS_EXTENSION changes the default .secret file extension
SECRETS_VERBOSE changes the output verbosity as documented at git-secret(7)
SECRETS_PINENTRY changes the gpg --pinentry mode as documented at git-secret(7)

MANUAL

Run man git-secret-hide to see this document.

git-secret

git-secret

git-secret - bash tool to store private data inside a git repo.

Usage: Setting up git-secret in a repository

Usage: Adding someone to a repository using git-secret

Using gpg

Using git-secret for Continuous Integration / Continuous Deployment (CI/CD)

Environment Variables and Configuration

The .gitsecret folder (can be overridden with SECRETS_DIR)

.gitsecret/paths

.gitsecret/keys

git-secret-whoknows

git-secret-whoknows - print email for each key in the keyring.

SYNOPSIS

DESCRIPTION

OPTIONS

MANUAL

SEE ALSO

git-secret-usage

git-secret-usage - prints all the available commands.

SYNOPSIS

DESCRIPTION

OPTIONS

MANUAL

SEE ALSO

git-secret-tell

git-secret-tell - adds person who can access private data.

SYNOPSIS

DESCRIPTION

OPTIONS

MANUAL

SEE ALSO

git-secret-reveal

git-secret-reveal - decrypts all added files.

SYNOPSIS

DESCRIPTION

OPTIONS

ENV VARIABLES

MANUAL

SEE ALSO

git-secret-removeperson

git-secret-removeperson - removes user’s public key from repo keyring.

SYNOPSIS

DESCRIPTION

OPTIONS

MANUAL

SEE ALSO

git-secret-remove

git-secret-remove - removes files from index.

SYNOPSIS

DESCRIPTION

OPTIONS

MANUAL

SEE ALSO

git-secret-list

git-secret-list - prints all the added files.

SYNOPSIS

DESCRIPTION

OPTIONS

MANUAL

SEE ALSO

git-secret-init

git-secret-init - initializes git-secret repository.

SYNOPSIS

DESCRIPTION

OPTIONS

MANUAL

SEE ALSO

git-secret-hide

git-secret-hide - encrypts all added files with repo keyring.

SYNOPSIS

DESCRIPTION

OPTIONS

ENV VARIABLES

MANUAL

SEE ALSO

The `.gitsecret` folder (can be overridden with `SECRETS_DIR`)

`.gitsecret/paths`

`.gitsecret/keys`