Archives/git-secret
2
1
Fork 0
mirror of https://github.com/sobolevn/git-secret synced 2024-10-31 21:20:29 +00:00
Code Issues Projects Releases Wiki Activity

documentation update (#355)

Browse Source
This commit is contained in:
Josh Rabinowitz 2019-02-11 09:37:09 -05:00 committed by GitHub
parent 6d77ef9a63
commit a3ee07c2f1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 629 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
_posts/2019-02-11-git-secret-add.md Normal file
View File

@ -0,0 +1,44 @@
---
layout: post
title: 'git-secret-add'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-add
categories: command
---
git-secret-add - starts to track added files.
=============================================
## SYNOPSIS
git secret add [-i] <pathspec>...
## DESCRIPTION
`git-secret-add` adds a filepath(s) into `.gitsecret/paths/mapping.cfg`.
When adding files to encrypt, ensure that they are ignored by `git` by mentioning
them in .gitignore, since they must be secure and not be committed into the remote repository unencrypted.
If there's no users in the `git-secret`'s keyring, when adding a file, an exception will be raised.
Use the `git secret add` command to add filenames to this file.
It is not recommended to add filenames directly into `.gitsecret/paths/mapping.cfg`.
(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret
folder using the SECRETS_DIR environment variable.
## OPTIONS
-i - adds given files to `.gitignore` if they're not there already
-h - shows this help.
## MANUAL
Run `man git-secret-add` to see this note.
## SEE ALSO
[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-tell(1)](http://git-secret.io/git-secret-tell),
[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal)

36
_posts/2019-02-11-git-secret-cat.md Normal file
View File

@ -0,0 +1,36 @@
---
layout: post
title: 'git-secret-cat'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-cat
categories: command
---
git-secret-cat - decrypts files passed on command line to stdout
=============================================
## SYNOPSIS
git secret cat [-d dir] [-p password] filename [filenames]
## DESCRIPTION
`git-secret-cat` - Outputs to stdout the contents of the files named on the command line.
As with `git-secret-reveal`, you'll need to have a public/private keypair that is allowed to
decrypt this repo.
## OPTIONS
-d - specifies `--homedir` option for the `gpg`, basically use this option if you store your keys in a custom location.
-p - specifies password for noinput mode, adds `--passphrase` option for `gpg`.
-h - shows help.
## MANUAL
Run `man git-secret-cat` to see this note.
## SEE ALSO
[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-tell(1)](http://git-secret.io/git-secret-tell), [git-secret-add(1)](http://git-secret.io/git-secret-add), [git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-cat)

39
_posts/2019-02-11-git-secret-changes.md Normal file
View File

@ -0,0 +1,39 @@
---
layout: post
title: 'git-secret-changes'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-changes
categories: command
---
git-secret-changes - view diff of the hidden files.
===================================================
## SYNOPSIS
git secret changes [-h] [-d dir] [-p password] [pathspec]...
## DESCRIPTION
`git-secret-changes` - shows changes between the current version of hidden files and the ones already committed.
You can provide any number of hidden files to this command as arguments, and it will show changes for these files only.
Note that files must be specified by their encrypted names, typically `filename.yml.secret`.
If no arguments are provided, information about all hidden files will be shown.
## OPTIONS
-d - specifies `--homedir` option for the `gpg`. Use this option if your store your keys in a custom location.
-p - specifies password for noinput mode, adds `--passphrase` option for `gpg`.
-h - shows help.
## MANUAL
Run `man git-secret-changes` to see this note.
## SEE ALSO
[git-secret-add(1)](http://git-secret.io/git-secret-add), [git-secret-tell(1)](http://git-secret.io/git-secret-tell),
[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal),
[git-secret-cat(1)](http://git-secret.io/git-secret-cat)

35
_posts/2019-02-11-git-secret-clean.md Normal file
View File

@ -0,0 +1,35 @@
---
layout: post
title: 'git-secret-clean'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-clean
categories: command
---
git-secret-clean - removes all the hidden files.
================================================
## SYNOPSIS
git secret clean [-v]
## DESCRIPTION
`git-secret-clean` deletes all the encrypted files.
Verbose output is enabled with the -v option, in which case the program prints which files are deleted.
## OPTIONS
-v - shows which files are deleted.
-h - shows this help.
## MANUAL
Run `man git-secret-clean` to see this note.
## SEE ALSO
[git-secret-whoknows(1)](http://git-secret.io/git-secret-whoknows), [git-secret-add(1)](http://git-secret.io/git-secret-add),
[git-secret-remove(1)](http://git-secret.io/git-secret-remove), [git-secret-killperson(1)](http://git-secret.io/git-secret-killperson)

65
_posts/2019-02-11-git-secret-hide.md Normal file
View File

@ -0,0 +1,65 @@
---
layout: post
title: 'git-secret-hide'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-hide
categories: command
---
git-secret-hide - encrypts all added files with the inner keyring.
==================================================================
## SYNOPSIS
git secret hide [-c] [-F] [-P] [-v] [-d] [-m]
## DESCRIPTION
`git-secret-hide` creates an encrypted version (typically called `filename.txt.secret`)
of each file added by `git-secret-add` command.
Now anyone enabled via 'git secret tell' can can decrypt these files. Under the hood,
`git-secret` uses the keyring in `.gitsecret/keys` and user's secret keys to decrypt the 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 keychain (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 option to force `git secret hide`
to skip any hidden files where the unencrypted versions aren't present.
Also, it is possible to modify the names of the encrypted files by setting `SECRETS_EXTENSION` variable.
(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret
folder using the SECRETS_DIR environment variable.
## 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.
## MANUAL
Run `man git-secret-hide` to see this note.
## SEE ALSO
[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-tell(1)](http://git-secret.io/git-secret-tell),
[git-secret-add(1)](http://git-secret.io/git-secret-add), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal),
[git-secret-cat(1)](http://git-secret.io/git-secret-cat)

36
_posts/2019-02-11-git-secret-init.md Normal file
View File

@ -0,0 +1,36 @@
---
layout: post
title: 'git-secret-init'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-init
categories: command
---
git-secret-init - initializes git-secret repository.
====================================================
## SYNOPSIS
git secret init
## DESCRIPTION
`git-secret-init` should be run inside a `git` repo to set up the .gitsecret directory and initialize the repo for git-secret.
Until repository is initialized with `git secret init`, all other `git-secret` commands are unavailable.
(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret
folder using the SECRETS_DIR environment variable.
## OPTIONS
-h - shows this help.
## MANUAL
Run `man git-secret-init` to see this note.
## SEE ALSO
[git-secret-usage(1)](http://git-secret.io/git-secret-usage), [git-secret-tell(1)](http://git-secret.io/git-secret-tell)

35
_posts/2019-02-11-git-secret-killperson.md Normal file
View File

@ -0,0 +1,35 @@
---
layout: post
title: 'git-secret-killperson'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-killperson
categories: command
---
git-secret-killperson - deletes key identified by an email from the inner keyring.
==================================================================================
## SYNOPSIS
git secret killperson <emails>...
## DESCRIPTION
This command removes the keys associated with the selected email addresses from the keyring.
If you remove a keypair's access with `git-secret-killperson`, and run `git-secret-reveal` and `git-secret-hide -r`,
it will be impossible for given users to decrypt the hidden files.
## OPTIONS
-h - shows this help.
## MANUAL
Run `man git-secret-killperson` to see this note.
## SEE ALSO
[git-secret-tell(1)](http://git-secret.io/git-secret-tell), [git-secret-remove(1)](http://git-secret.io/git-secret-remove),
[git-secret-clean(1)](http://git-secret.io/git-secret-clean)

37
_posts/2019-02-11-git-secret-list.md Normal file
View File

@ -0,0 +1,37 @@
---
layout: post
title: 'git-secret-list'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-list
categories: command
---
git-secret-list - prints all the added files.
=============================================
## SYNOPSIS
git secret list
## DESCRIPTION
`git-secret-list` prints all the currently added tracked files from the `.gitsecret/paths/mapping.cfg`.
(See [git-secret(7)](http://git-secret.io/git-secret) 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 note.
## SEE ALSO
[git-secret-whoknows(1)](http://git-secret.io/git-secret-whoknows), [git-secret-add(1)](http://git-secret.io/git-secret-add),
[git-secret-remove(1)](http://git-secret.io/git-secret-remove), [git-secret-hide(1)](http://git-secret.io/git-secret-hide),
[git-secret-reveal(1)](http://git-secret.io/git-secret-reveal), [git-secret-cat(1)](http://git-secret.io/git-secret-cat)

39
_posts/2019-02-11-git-secret-remove.md Normal file
View File

@ -0,0 +1,39 @@
---
layout: post
title: 'git-secret-remove'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-remove
categories: command
---
git-secret-remove - removes files from index.
=============================================
## SYNOPSIS
git secret remove [-c] <pathspec>...
## DESCRIPTION
`git-secret-remove` deletes files from `.gitsecret/paths/mapping.cfg`,
so they won't be encrypted or decrypted in the future.
There's also a -c option to delete existing encrypted versions of the files provided.
(See [git-secret(7)](http://git-secret.io/git-secret) 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 note.
## SEE ALSO
[git-secret-add(1)](http://git-secret.io/git-secret-add), [git-secret-clean(1)](http://git-secret.io/git-secret-clean),
[git-secret-killperson(1)](http://git-secret.io/git-secret-killperson)

46
_posts/2019-02-11-git-secret-reveal.md Normal file
View File

@ -0,0 +1,46 @@
---
layout: post
title: 'git-secret-reveal'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-reveal
categories: command
---
git-secret-reveal - decrypts all added files.
=============================================
## SYNOPSIS
git secret reveal [-f] [-F] [-P] [-d dir] [-p password] [pathspec]...
## DESCRIPTION
`git-secret-reveal` - decrypts all the files in `.gitsecret/paths/mapping.cfg`,
or the passed `pathspec`s.
You will need to have imported the paired secret-key with one of the
public-keys which were used in the encryption.
Under the hood, this uses the `gpg --decrypt` command.
(See [git-secret(7)](http://git-secret.io/git-secret) for information about renaming the .gitsecret
folder using the SECRETS_DIR environment variable.
## 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.
-p - specifies password for noinput mode, adds `--passphrase` option for `gpg`.
-P - preserve permissions of encrypted file in unencrypted file.
-h - shows help.
## MANUAL
Run `man git-secret-reveal` to see this note.
## SEE ALSO
[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-cat(1)](http://git-secret.io/git-secret-cat),
[git-secret-tell(1)](http://git-secret.io/git-secret-tell), [git-secret-add(1)](http://git-secret.io/git-secret-add),
[git-secret-hide(1)](http://git-secret.io/git-secret-hide)

42
_posts/2019-02-11-git-secret-tell.md Normal file
View File

@ -0,0 +1,42 @@
---
layout: post
title: 'git-secret-tell'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-tell
categories: command
---
git-secret-tell - adds a person, who can access private data.
===============================================================
## SYNOPSIS
git secret tell [-m] [-d dir] [emails]...
## DESCRIPTION
`git-secret-tell` receives an email addresses as an input, searches for the `gpg`-key in the `gpg`'s
`homedir` by these emails, then imports a person's public key into the `git-secret`'s inner keychain.
From this moment this person can encrypt new files with the keyring which contains their key,
but they cannot decrypt the old files, which were already encrypted without their key.
The files should be re-encrypted with the new keyring by someone who has the unencrypted files.
**Do not manually import secret key into `git-secret`**. Anyways, it won't work with any of the secret-keys imported.
## OPTIONS
-m - takes your current `git config user.email` as an identifier for the key.
-d - specifies `--homedir` option for the `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 note.
## SEE ALSO
[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-add(1)](http://git-secret.io/git-secret-add),
[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal),
[git-secret-cat(1)](http://git-secret.io/git-secret-cat), [git-secret-killperson(1)](http://git-secret.io/git-secret-killperson)

34
_posts/2019-02-11-git-secret-usage.md Normal file
View File

@ -0,0 +1,34 @@
---
layout: post
title: 'git-secret-usage'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-usage
categories: command
---
git-secret-usage - prints all the available commands.
=====================================================
## SYNOPSIS
git secret usage
## DESCRIPTION
`git-secret-usage` is used to print all the available commands.
## OPTIONS
-h - shows this help.
## MANUAL
Run `man git-secret-usage` to see this note.
## SEE ALSO
[git-secret-init(1)](http://git-secret.io/git-secret-init), [git-secret-add(1)](http://git-secret.io/git-secret-add),
[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal),
[git-secret-cat(1)](http://git-secret.io/git-secret-cat)

35
_posts/2019-02-11-git-secret-whoknows.md Normal file
View File

@ -0,0 +1,35 @@
---
layout: post
title: 'git-secret-whoknows'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret-whoknows
categories: command
---
git-secret-whoknows - prints email-labels for each key in the keyring.
======================================================================
## SYNOPSIS
git secret whoknows
## DESCRIPTION
`git-secret-whoknows` prints list of email addresses whose keys are 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 note.
## SEE ALSO
[git-secret-list(1)](http://git-secret.io/git-secret-list), [git-secret-tell(1)](http://git-secret.io/git-secret-tell),
[git-secret-hide(1)](http://git-secret.io/git-secret-hide), [git-secret-reveal(1)](http://git-secret.io/git-secret-reveal),
[git-secret-cat(1)](http://git-secret.io/git-secret-cat)

106
_posts/2019-02-11-git-secret.md Normal file
View File

@ -0,0 +1,106 @@
---
layout: post
title: 'git-secret'
date: 2019-02-11 09:26:41 -0500
permalink: git-secret
categories: usage
---
## Usage: Setting up git-secret in a repository
These steps cover the basic process of using `git-secret`:
0. Before starting, make sure you have created `gpg` RSA key-pair: public and secret key identified by your email address.
1. Begin with an existing or new git repository. You'll use the 'git secret' commands to add the keyrings and information
to make the git-secret hide and reveal files in this repository.
2. Initialize the `git-secret` repository by running `git secret init` command. the `.gitsecret/` folder will be created,
**Note** all the contents of the `.gitsecret/` folder should be checked in, /except/ the `random_seed` file.
In other words, of the files in .gitsecret, only the random_seed file should be mentioned in your .gitignore file.
3. Add the first user to the git-secret repo keyring by running `git secret tell your@gpg.email`.
4. Now it's time to add files you wish to encrypt inside the `git-secret` repository.
It can be done by running `git secret add <filenames...>` command. Make sure these files are ignored by mentions in
.gitignore, otherwise `git-secret` won't allow you to add them, as these files could be stored unencrypted.
5. When done, run `git secret hide` to encrypt all files which you have added by the `git secret add` command.
The data will be encrypted with the public-keys described by the `git secret tell` command.
After using `git secret hide` to encrypt your data, it is safe to commit your changes.
**NOTE:**. It's recommended to add `git secret hide` command to your `pre-commit` hook, so you won't miss any changes.
6. Later you can decrypt files with the `git secret reveal` command, or just show 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
1. Get their `gpg` public-key. **You won't need their secret key.**
2. Import this key into your `gpg` setup (in ~/.gnupg or similar) by running `gpg --import KEY_NAME.txt`
3. Now add this person to your secrets repo by running `git secret tell persons@email.id`
(this will be the email address associated with the public key)
4. 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 be able to decrypt the files in the repo using `git-secret`.
Note that it is possible to add yourself to the git-secret repo without decrypting existing files.
It will be possible to decrypt them after re-encrypting them with the new keyring. So, if you don't
want unexpected keys added, you can configure some server-side security policy with the `pre-receive` hook.
## 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.
The settings available to be changed are:
* `$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 to be working with: `gpg`, `gpg2`.
* `$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.
## 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. Thus it is best to use
git-secret with the same version of gpg being used by all users.
This can be forced using SECRETS_GPG_COMMAND environment variable.
Specifically, 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').
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 your storing encrypted.
In other words, the path mappings: what files are tracked to be hidden and revealed.
All the other internal data is stored in the directory:
### `.gitsecret/keys`
This directory contains data used by git-secret and PGP to allow and maintain the correct encryption and access rights for the permitted parties.
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.