git-secret/man/man7/git-secret.7
2022-07-23 12:32:33 +03:00

254 lines
12 KiB
Groff
Generated

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "GIT\-SECRET" "7" "June 2022" "sobolevn" "git-secret 0.5.1-alpha1"
.
.SH "NAME"
\fBgit\-secret\fR \- bash tool to store private data inside a git repo\.
.
.SH "Usage: Setting up git\-secret in a repository"
These steps cover the basic process of using \fBgit\-secret\fR to specify users and files that will interact with \fBgit\-secret\fR, and to encrypt and decrypt secrets\.
.
.IP "1." 4
Before starting, \fImake sure you have created a \fBgpg\fR RSA key\-pair\fR: 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\.
.
.IP "2." 4
Begin with an existing or new git repository\.
.
.IP "3." 4
Initialize the \fBgit\-secret\fR repository by running \fBgit secret init\fR\. The \fB\.gitsecret/\fR folder will be created, with subdirectories \fBkeys/\fR and \fBpaths/\fR, \fB\.gitsecret/keys/random_seed\fR will be added to \fB\.gitignore\fR, and \fB\.gitignore\fR will be configured to \fInot\fR ignore \fB\.secret\fR files\.
.
.IP "" 0
.
.P
\fBNote\fR all the contents of the \fB\.gitsecret/\fR folder should be checked in, \fB/except/\fR the \fBrandom_seed\fR file\. This also means that of all the files in \fB\.gitsecret/\fR, only the \fBrandom_seed\fR file should be mentioned in your \fB\.gitignore\fR file\.
.
.IP "1." 4
Add the first user to the \fBgit\-secret\fR repo keyring by running \fBgit secret tell your@email\.id\fR\.
.
.IP "2." 4
Now it\'s time to add files you wish to encrypt inside the \fBgit\-secret\fR repository\. This can be done by running \fBgit secret add <filenames\.\.\.>\fR command, which will also (as of 0\.2\.6) add entries to \fB\.gitignore\fR, stopping those files from being added or committed to the repo unencrypted\.
.
.IP "3." 4
Then run \fBgit secret hide\fR to encrypt the files you added with \fBgit secret add\fR\. 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 \fBtell\fR\.
.
.IP "" 0
.
.P
After using \fBgit secret hide\fR to encrypt your data, it is safe to commit your changes\. \fBNOTE:\fR It\'s recommended to add the \fBgit secret hide\fR command to your \fBpre\-commit\fR hook, so you won\'t miss any changes\.
.
.IP "1." 4
Later you can decrypt files with the \fBgit secret reveal\fR command, or print their contents to stdout with the \fBgit secret cat\fR command\. If you used a password on your GPG key (always recommended), it will ask you for your password\. And you\'re done!
.
.IP "" 0
.
.SS "Usage: Adding someone to a repository using git\-secret"
.
.IP "1." 4
\fIGet their \fBgpg\fR public\-key\fR\. \fBYou won\'t need their secret key\.\fR They can export their public key for you using a command like: \fBgpg \-\-armor \-\-export their@email\.id > public_key\.txt # \-\-armor here makes it ascii\fR
.
.IP "2." 4
Import this key into your \fBgpg\fR keyring (in \fB~/\.gnupg\fR or similar) by running \fBgpg \-\-import public_key\.txt\fR
.
.IP "3." 4
Now add this person to your secrets repo by running \fBgit secret tell their@email\.id\fR (this will be the email address associated with their public key)
.
.IP "4." 4
Now remove the other user\'s public key from your personal keyring with \fBgpg \-\-delete\-keys their@email\.id\fR
.
.IP "5." 4
The newly added user cannot yet read the encrypted files\. Now, re\-encrypt the files using \fBgit secret reveal; git secret hide \-d\fR, 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 \fBgit\-secret reveal\fR\.
.
.IP "" 0
.
.P
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\.
.
.P
If you do not want unexpected keys added, you can configure some server\-side security policy with the \fBpre\-receive\fR hook\.
.
.SS "Using gpg"
You can follow a quick \fBgpg\fR tutorial at devdungeon \fIhttps://www\.devdungeon\.com/content/gpg\-tutorial\fR\. Here are the most useful commands to get started:
.
.P
To generate a RSA key\-pair, run:
.
.IP "" 4
.
.nf
gpg \-\-gen\-key
.
.fi
.
.IP "" 0
.
.P
To export your public key, run:
.
.IP "" 4
.
.nf
gpg \-\-armor \-\-export your\.email@address\.com > public\-key\.gpg
.
.fi
.
.IP "" 0
.
.P
To import the public key of someone else (to share the secret with them for instance), run:
.
.IP "" 4
.
.nf
gpg \-\-import public\-key\.gpg
.
.fi
.
.IP "" 0
.
.P
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!
.
.SS "Using git\-secret for Continuous Integration / Continuous Deployment (CI/CD)"
When using \fBgit\-secret\fR 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\.
.
.P
One way of doing it is the following:
.
.IP "1." 4
\fIcreate a gpg key\fR for your CI/CD environment\. You can chose any name and email address you want: for instance \fBMyApp Example <myapp@example\.com>\fR 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\.
.
.IP "2." 4
run \fBgpg \-\-armor \-\-export\-secret\-key myapp@example\.com\fR to get your private key value
.
.IP "3." 4
Create an env var on your CI/CD server \fBGPG_PRIVATE_KEY\fR 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 \fBGPG_PASSPHRASE\fR and assign it the passphrase of the private key\.
.
.IP "4." 4
Then write your Continuous Deployment build script\. For instance:
.
.IP "" 0
.
.IP "" 4
.
.nf
# 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 \.\.\.
.
.fi
.
.IP "" 0
.
.P
Note: your CI/CD might not allow you to create a multiline value\. In that case, you can export it on one line with
.
.IP "" 4
.
.nf
gpg \-\-armor \-\-export\-secret\-key myapp@example\.com | tr \'\en\' \',\'
.
.fi
.
.IP "" 0
.
.P
You can then create your private key file with:
.
.IP "" 4
.
.nf
echo "$GPG_PRIVATE_KEY" | tr \',\' \'\en\' > \./private_key\.gpg
.
.fi
.
.IP "" 0
.
.P
Also note: the \fBgpg\fR version on the CI/CD server \fBMUST INTEROPERATE\fR with the one used locally\. Otherwise, \fBgpg\fR decryption can fail, which leads to \fBgit secret reveal\fR reporting \fBcannot find decrypted version of file\fR error\. The best way to ensure this is to use the same version of gnupg on different systems\.
.
.SH "Environment Variables and Configuration"
You can configure the version of \fBgpg\fR 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 \fBgit\-secret\fR command\. See below, or the man page of \fBgit\-secret\fR for an explanation of the environment variables \fBgit\-secret\fR uses\.
.
.P
The settings available to be changed are:
.
.IP "\(bu" 4
\fB$SECRETS_VERBOSE\fR \- sets the verbose flag to on for all \fBgit\-secret\fR commands; is identical to using \fB\-v\fR on each command that supports it\.
.
.IP "\(bu" 4
\fB$SECRETS_GPG_COMMAND\fR \- sets the \fBgpg\fR alternatives, defaults to \fBgpg\fR\. It can be changed to \fBgpg\fR, \fBgpg2\fR, \fBpgp\fR, \fB/usr/local/gpg\fR or any other value\. After doing so rerun the tests to be sure that it won\'t break anything\. Tested with \fBgpg\fR and \fBgpg2\fR\.
.
.IP "\(bu" 4
\fB$SECRETS_GPG_ARMOR\fR \- sets the \fBgpg\fR \fB\-\-armor\fR mode \fIhttps://www\.gnupg\.org/gph/en/manual/r1290\.html\fR\. Can be set to \fB1\fR to store secrets file as text\. By default is \fB0\fR and store files as binaries\.
.
.IP "\(bu" 4
\fB$SECRETS_EXTENSION\fR \- sets the secret files extension, defaults to \fB\.secret\fR\. It can be changed to any valid file extension\.
.
.IP "\(bu" 4
\fB$SECRETS_DIR\fR \- sets the directory where \fBgit\-secret\fR stores its files, defaults to \fB\.gitsecret\fR\. It can be changed to any valid directory name\.
.
.IP "\(bu" 4
\fB$SECRETS_PINENTRY\fR \- allows user to specify a setting for \fBgpg\fR\'s \fB\-\-pinentry\fR option\. See \fBgpg\fR docs \fIhttps://github\.com/gpg/pinentry\fR for details about gpg\'s \fB\-\-pinentry\fR option\.
.
.IP "" 0
.
.SH "The <code>\.gitsecret</code> folder (can be overridden with <code>SECRETS_DIR</code>)"
This folder contains information about the files encrypted by git\-secret, and about which public/private key sets can access the encrypted data\.
.
.P
You can change the name of this directory using the SECRETS_DIR environment variable\.
.
.P
Use the various \fBgit\-secret\fR commands to manipulate the files in \fB\.gitsecret\fR, you should not change the data in these files directly\.
.
.P
Exactly which files exist in the \fB\.gitsecret\fR 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 \fBSECRETS_GPG_COMMAND\fR environment variable\.
.
.P
For example, there is an issue between \fBgpg\fR 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\')\.
.
.P
This is not the only issue it is possible to encounter sharing files between different versions of \fBgpg\fR\. Generally you are most likely to encounter issues between \fBgpg\fR versions if you use \fBgit\-secret tell\fR or \fBgit\-secret removeperson\fR to modify your repo\'s \fBgit\-secret\fR keyring using a newer version of \fBgpg\fR, and then try to operate on that keyring using an older version of \fBgpg\fR\.
.
.P
The \fBgit\-secret\fR internal data is separated into two directories:
.
.SS "<code>\.gitsecret/paths</code>"
This directory currently contains only the file \fBmapping\.cfg\fR, 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\.
.
.P
All other internal data used by git\-secret is stored in the directory:
.
.SS "<code>\.gitsecret/keys</code>"
This directory contains data used by \fBgit\-secret\fR and \fBgpg\fR to encrypt files to be accessed by the permitted users\.
.
.P
In particular, this directory contains a \fBgnupg keyring\fR with public keys for the emails used with \fBtell\fR\.
.
.P
This is the keyring used to encrypt files with \fBgit\-secret\-hide\fR\.
.
.P
\fBgit\-secret\-reveal\fR and \fBgit\-secret\-cat\fR, which decrypt secrets, instead use the user\'s \fIprivate keys\fR (which probably reside somewhere like ~/\.gnupg/)\. Note that user\'s private keys, needed for decryption, are \fInot\fR in the \fB\.gitsecret/keys\fR directory\.
.
.P
Generally speaking, all the files in this directory \fIexcept\fR \fBrandom_seed\fR should be checked into your repo\. By default, \fBgit secret init\fR will add the file \fB\.gitsecret/keys/random_seed\fR to your \fB\.gitignore\fR file\.
.
.P
Again, you can change the name of this directory using the SECRETS_DIR environment variable\.