You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
git-secret/man/man7/git-secret.7

85 lines
4.6 KiB
Groff

9 years ago
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "GIT\-SECRET" "7" "April 2018" "sobolevn" "git-secret"
9 years ago
.
.SH "NAME"
\fBgit\-secret\fR
.
9 years ago
.SH "Usage"
9 years ago
These steps cover the basic process of using \fBgit\-secret\fR:
.
.IP "1." 4
Before starting, make sure you have created \fBgpg\fR RSA key\-pair: public and secret key identified by your email address\.
.
.IP "2." 4
Initialize \fBgit\-secret\fR repository by running \fBgit secret init\fR command\. \fB\.gitsecret/\fR folder will be created, \fBnote\fR that \fB\.gitsecret/\fR folder with the exception of the random_seed file should \fBnot\fR ignored via inclusion in your \.gitignore file \fIhttps://github\.com/sobolevn/git\-secret/issues/39\fR\.
9 years ago
.
.IP "3." 4
Add first user to the system by running \fBgit secret tell your@gpg\.email\fR\.
9 years ago
.
.IP "4." 4
Now it\'s time to add files you wish to encrypt inside the \fBgit\-secret\fR repository\. It can be done by running \fBgit secret add <filenames\.\.\.>\fR command\. Make sure these files are ignored by mentions in \.gitignore, otherwise \fBgit\-secret\fR won\'t allow you to add them, as these files could be stored unencrypted\.
9 years ago
.
.IP "5." 4
When done, run \fBgit secret hide\fR to encrypt all files which you have added by the \fBgit secret add\fR command\. The data will be encrypted with the public\-keys described by the \fBgit secret tell\fR command\. After using \fBgit secret hide\fR to encrypt your data, it is safe to commit your changes\. \fBNOTE:\fR\. It\'s recommended to add \fBgit secret hide\fR command to your \fBpre\-commit\fR hook, so you won\'t miss any changes\.
9 years ago
.
.IP "6." 4
Later you can decrypt files with the \fBgit secret reveal\fR command, or just show their contents to strdout with the \fBgit secret cat\fR command\. If you used a password on you GPG key (always recommended), it will ask you for your password\. And you\'re done!
9 years ago
.
.IP "" 0
9 years ago
.
.SS "I want to add someone to the repository"
.
.IP "1." 4
Get their \fBgpg\fR public\-key\. \fBYou won\'t need their secret key\.\fR
9 years ago
.
.IP "2." 4
Import this key inside your \fBgpg\fR setup (in ~/\.gnupg or similar) by running \fBgpg \-\-import KEY_NAME\fR
9 years ago
.
.IP "3." 4
Now add this person to your secrets repo by running \fBgit secret tell persons@email\.id\fR
9 years ago
.
.IP "4." 4
Then re\-encrypt the files using \fBgit secret reveal; git secret hide \-d\fR\. (The \-d options deletes the unencrypted file after re\-encrypting it)\. Now the newly added user be able to decrypt them using \fBgit\-secret\fR and their secret key\.
9 years ago
.
.IP "" 0
.
.P
Note that it is possible to add yourself to the system without decrypting existing files\. It will be possible to decrypt them after reencrypting them with the new keyring\. So, if you don\'t want unexpected keys added, make sure to configure some server\-side security policy with the \fBpre\-receive\fR hook\.
.
.SH "Configuration"
You can configure several things 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 the each \fBgit\-secret\fR command\.
.
.P
These settings are available to be changed:
.
.IP "\(bu" 4
7 years ago
\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 to be working with: \fBgpg\fR, \fBgpg2\fR\.
.
.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 "" 0
.
.SH "Internals \-\- the <code>\.gitsecret</code> folder"
This folder contains all the information about the data encrypted in this repo\. Use the \'git secret\' commands to manipulate these files, you should not change the data in these files directly\.
.
.P
The data is separated into two directories:
.
.SS "<code>\.gitsecret/paths</code>"
which currently contains only the file \fBmapping\.cfg\fR, which lists all the files your storing encrypted\. In other words, the path mappings: what files are tracked to be hidden and revealed\.
.
.P
All the other internal data is stored in the directory:
.
.SS "<code>\.gitsecret/keys</code>"
This folder contains data used by git\-secret and PGP to allow and maintain the correct encyption and access rights for the allowed parties\.
.
.P
Generally speaking, all the files in this directory except \fBrandom_seed\fR should be checked into your secrets repo\.
.
.br
By default, \fBgit secret init\fR will add the file \fB\.gitsecret/keys/random_seed\fR to your \.gitignore file\.