From b6d903b2a6e8456512c84b80d307129f7fcc01a2 Mon Sep 17 00:00:00 2001 From: Josh Rabinowitz Date: Mon, 16 Apr 2018 16:07:56 -0400 Subject: [PATCH] improve docs re: ignores & .gitsecret --- CHANGELOG.md | 1 + man/man1/git-secret-add.1 | 2 +- man/man1/git-secret-add.1.ronn | 2 +- man/man7/git-secret.7 | 39 +++++++++++++++++++--------------- man/man7/git-secret.7.ronn | 37 ++++++++++++++++++++------------ 5 files changed, 48 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 16545499..3422bb01 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## Version 0.2.4 - Added `git secret cat` feature (#141) +- Documentation improvements (#144) ## Version 0.2.3 diff --git a/man/man1/git-secret-add.1 b/man/man1/git-secret-add.1 index 5bc9bb33..c2a993bb 100644 --- a/man/man1/git-secret-add.1 +++ b/man/man1/git-secret-add.1 @@ -15,7 +15,7 @@ git secret add [\-i] \.\.\. .fi . .SH "DESCRIPTION" -\fBgit\-secret\-add\fR adds a filepath(es) into the \fB\.gitsecret/paths/mapping\.cfg\fR\. When adding files, ensure that they are ignored by \fBgit\fR, since they must be secure and not be commited into the remote repository unencrypted\. +\fBgit\-secret\-add\fR adds a filepath(es) into the \fB\.gitsecret/paths/mapping\.cfg\fR\. When adding files to encrypt, ensure that they are ignored by \fBgit\fR by mentioning them in \.gitignore, since they must be secure and not be committed into the remote repository unencrypted\. . .P If there\'s no users in the \fBgit\-secret\fR\'s keyring, when adding a file, an exception will be raised\. diff --git a/man/man1/git-secret-add.1.ronn b/man/man1/git-secret-add.1.ronn index 3f182027..5d5f4778 100644 --- a/man/man1/git-secret-add.1.ronn +++ b/man/man1/git-secret-add.1.ronn @@ -7,7 +7,7 @@ git-secret-add - starts to track added files. ## DESCRIPTION -`git-secret-add` adds a filepath(es) into the `.gitsecret/paths/mapping.cfg`. When adding files, ensure that they are ignored by `git`, since they must be secure and not be commited into the remote repository unencrypted. +`git-secret-add` adds a filepath(es) into the `.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. diff --git a/man/man7/git-secret.7 b/man/man7/git-secret.7 index 752424b6..aea6a0d4 100644 --- a/man/man7/git-secret.7 +++ b/man/man7/git-secret.7 @@ -13,19 +13,19 @@ These steps cover the basic process of using \fBgit\-secret\fR: 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 should \fBnot\fR be ignored \fIhttps://github\.com/sobolevn/git\-secret/issues/39\fR\. +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\. . .IP "3." 4 Add first user to the system by running \fBgit secret tell your@gpg\.email\fR\. . .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 \fR command\. Make sure these files are ignored, otherwise \fBgit\-secret\fR won\'t allow you to add them, as these files will be stored unencrypted\. +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 \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\. . .IP "5." 4 -When done, run \fBgit secret hide\fR all files, which you have added by \fBgit secret add\fR command will be encrypted with added public\-keys by the \fBgit secret tell\fR command\. Now it is safe to commit your changes\. \fBBut\fR\. It\'s recommended to add \fBgit secret hide\fR command to your \fBpre\-commit\fR hook, so you won\'t miss any changes\. +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\. . .IP "6." 4 -Now decrypt files with \fBgit secret reveal\fR command\. It will ask you for your password\. And you\'re done! +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! . .IP "" 0 . @@ -35,18 +35,18 @@ Now decrypt files with \fBgit secret reveal\fR command\. It will ask you for you Get their \fBgpg\fR public\-key\. \fBYou won\'t need their secret key\.\fR . .IP "2." 4 -Import this key inside your \fBgpg\fR by running \fBgpg \-\-import KEY_NAME\fR +Import this key inside your \fBgpg\fR setup (in ~/\.gnupg or similar) by running \fBgpg \-\-import KEY_NAME\fR . .IP "3." 4 -Now add this person to the \fBgit\-secret\fR by running \fBgit secret tell persons@email\.id\fR +Now add this person to your secrets repo by running \fBgit secret tell persons@email\.id\fR . .IP "4." 4 -Reencypt the files, now they will be able to decrypt them with their secret key\. +Then re\-encrypt the files using \fBgit secret show; git secret hide\fR\. Now the newly added user be able to decrypt them using \fBgit\-secret\fR and their secret key\. . .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\. +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\. @@ -62,18 +62,23 @@ These settings are available to be changed: . .IP "" 0 . -.SH "Internals" +.SH "Internals \-\- the \.gitsecret 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\. . -.SS "\.gitsecret folder" -This folder contains every piece of information about the project\. It stores: +.P +The data is separated into two directories: . -.IP "\(bu" 4 -public keys for the project +.SS "\.gitsecret/paths" +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\. . -.IP "\(bu" 4 -path mappings\. Or in other words: what files are tracked to be hidden and revealed +.P +All the other internal data is stored in the directory: . -.IP "" 0 +.SS "\.gitsecret/keys" +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 -This folder should not be ignored\. In case it is application would not work raising an error: \fB\'\.gitsecret/\' is ignored\. abort\.\'\fR\. However, it is possible to ignore individual files \fIhttps://github\.com/sobolevn/git\-secret/issues/93\fR inside it: \fBrandom_seed\fR would be the most popular example\. +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\. diff --git a/man/man7/git-secret.7.ronn b/man/man7/git-secret.7.ronn index 14e3bca5..d230a739 100644 --- a/man/man7/git-secret.7.ronn +++ b/man/man7/git-secret.7.ronn @@ -3,20 +3,20 @@ 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. Initialize `git-secret` repository by running `git secret init` command. `.gitsecret/` folder will be created, **note** that `.gitsecret/` folder [should **not** be ignored](https://github.com/sobolevn/git-secret/issues/39). +1. Initialize `git-secret` repository by running `git secret init` command. `.gitsecret/` folder will be created, **note** that `.gitsecret/` folder with the exception of the random_seed file [should **not** ignored via inclusion in your .gitignore file](https://github.com/sobolevn/git-secret/issues/39). 2. Add first user to the system by running `git secret tell your@gpg.email`. -3. 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 ` command. Make sure these files are ignored, otherwise `git-secret` won't allow you to add them, as these files will be stored unencrypted. -4. When done, run `git secret hide` all files, which you have added by `git secret add` command will be encrypted with added public-keys by the `git secret tell` command. Now it is safe to commit your changes. **But**. It's recommended to add `git secret hide` command to your `pre-commit` hook, so you won't miss any changes. -5. Now decrypt files with `git secret reveal` command. It will ask you for your password. And you're done! +3. 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 ` 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. +4. 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. +5. Later you can decrypt files with the `git secret reveal` command, or just show their contents to strdout with the `git secret cat` command. If you used a password on you GPG key (always recommended), it will ask you for your password. And you're done! ### I want to add someone to the repository 1. Get their `gpg` public-key. **You won't need their secret key.** -2. Import this key inside your `gpg` by running `gpg --import KEY_NAME` -3. Now add this person to the `git-secret` by running `git secret tell persons@email.id` -4. Reencypt the files, now they will be able to decrypt them with their secret key. +2. Import this key inside your `gpg` setup (in ~/.gnupg or similar) by running `gpg --import KEY_NAME` +3. Now add this person to your secrets repo by running `git secret tell persons@email.id` +4. Then re-encrypt the files using `git secret show; git secret hide`. Now the newly added user be able to decrypt them using `git-secret` and their secret key. -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 `pre-receive` hook. +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 `pre-receive` hook. ## Configuration @@ -27,13 +27,22 @@ These settings are available to be changed: * `$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. -## Internals +## Internals -- the `.gitsecret` folder -### `.gitsecret` 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. -This folder contains every piece of information about the project. It stores: +The data is separated into two directories: -* public keys for the project -* path mappings. Or in other words: what files are tracked to be hidden and revealed +### `.gitsecret/paths` -This folder should not be ignored. In case it is application would not work raising an error: `'.gitsecret/' is ignored. abort.'`. However, it is possible to ignore [individual files](https://github.com/sobolevn/git-secret/issues/93) inside it: `random_seed` would be the most popular example. +which 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 folder contains data used by git-secret and PGP to allow and maintain the correct encyption and access rights for the allowed parties. + +Generally speaking, all the files in this directory except `random_seed` should be checked into your secrets repo. +By default, `git secret init` will add the file `.gitsecret/keys/random_seed` to your .gitignore file.