From a1013791ed8414d4163123f0520a4180964f3a4a Mon Sep 17 00:00:00 2001 From: Josh Rabinowitz Date: Sun, 24 Apr 2022 11:15:14 -0400 Subject: [PATCH] More doc improvements (#847) --- docs/installation.md | 47 ++++++++++++++--------------- man/man1/git-secret-add.1 | Bin 1542 -> 1542 bytes man/man1/git-secret-cat.1 | Bin 1481 -> 1481 bytes man/man1/git-secret-changes.1 | Bin 1748 -> 1748 bytes man/man1/git-secret-clean.1 | Bin 1486 -> 1486 bytes man/man1/git-secret-hide.1 | Bin 3695 -> 3695 bytes man/man1/git-secret-init.1 | Bin 1726 -> 1726 bytes man/man1/git-secret-list.1 | Bin 1193 -> 1193 bytes man/man1/git-secret-remove.1 | Bin 1449 -> 1449 bytes man/man1/git-secret-removeperson.1 | Bin 1185 -> 1185 bytes man/man1/git-secret-reveal.1 | Bin 2733 -> 2733 bytes man/man1/git-secret-tell.1 | Bin 2501 -> 2501 bytes man/man1/git-secret-usage.1 | Bin 877 -> 877 bytes man/man1/git-secret-whoknows.1 | Bin 967 -> 967 bytes man/man7/git-secret.7 | Bin 11697 -> 12347 bytes man/man7/git-secret.7.md | 42 +++++++++++++++++--------- 16 files changed, 50 insertions(+), 39 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index bfb93b0e..8dcd0427 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -27,14 +27,13 @@ Also we welcome improvements to tests or `git-secret` code for any platform. ## Installation process There are several ways to install `git-secret`, depending on your OS and distribution. -They generally all have different installation processes, and we only go into -a short explanation, because describing how to install the prerequisites on all -systems is currently outside the scope of this document. +They generally all have different installation processes, so we only go into +a short explanation of each. (We welcome documentation improvements.) --- -### Mac OS X/Homebrew +### Mac OS X / Homebrew This is a packaging system for OSX. To install `git-secret` on OSX, you can install `homebrew` and then use: @@ -45,7 +44,7 @@ brew install git-secret --- -### Debian-Type Systems/`deb` package +### Debian-Type Systems / `deb` package `deb` is a packaging system for [Debian](https://www.debian.org/) and related linux distributions. @@ -59,7 +58,7 @@ Pre-requirements: make sure you have installed `apt-transport-https` and `ca-cer --- -### Red Hat Systems/`rpm` package +### Red Hat Systems / `rpm` package `rpm` is a packaging system for Fedora, CentOS, and other Red Hat based linux distributions. You can find the `rpm` repository [here](https://gitsecret.jfrog.io/artifactory/git-secret-rpm/). @@ -70,7 +69,7 @@ You can find the `rpm` repository [here](https://gitsecret.jfrog.io/artifactory/ --- -### Alpine Systems/`apk` package +### Alpine Systems / `apk` package `apk` is a packaging system for Alpine. You can find the `apk` `git-secret` packaging @@ -84,7 +83,7 @@ and you can see a list of supported architectures --- -### Arch Linux/`PKGBUILD` or `AUR` +### Arch Linux / `PKGBUILD` or `AUR` The _Arch_ way to install git-secret is to use the directions for "Installing Packages" at [Arch User Repository Documentation](https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages) @@ -99,22 +98,23 @@ yay -S git-secret --- -### Windows/`WSL`, `Cygwin`, `MSYS`, or `Mingw-w64` +### Windows / `WSL`, `Cygwin`, `MSYS`, or `Mingw-w64` `git-secret` depends on many unix tools and features that Windows systems do not usually include by default. Therefore to get `git-secret` running on Windows you have to install these tools, probably using one of the toolkits described below. -(Each has a different install and setup process, and there may be additional -package systems to install the prerequisites on Windows). +Each has a different install and setup process. There may also be other +ways to install the unix prerequisites on Windows. -Then, once the prerequisite unix tools are installed, +Once the prerequisite unix tools are installed, you can use the Manual Installation instructions below to manually install `git-secret` (see below). -Some options to install the required unix tools on your windows system include -WSL, CYGWIN, MSYS, and Mingw-w64 (which may have some overlap). +Some ways to install the required unix tools on windows include +WSL, CYGWIN, MSYS, and Mingw-w64 +(internally, these tools may share some components). -Documenting how each is installed and operates is beyond the scope of this document, +Documenting how each is installed and used is beyond the scope of this document, so we will cover the topic in broad strokes. Improvements to this documentation (or any other git-secret documentation) are welcome. @@ -125,31 +125,28 @@ Again, after you install the unix tools needed, you can install Perhaps the easiest way to get `git-secret` operating on windows is using `WSL` (if your system supports it). -You'll need to install these additional packages: `gnupg make man git gawk file`. Here are instructions to install [WSL](https://docs.microsoft.com/en-us/windows/wsl/install) +You'll need to install these additional packages: `gnupg`, `make`, `man`, `git`, `gawk`, `file`. We have successfully set up automated testing of `git-secret` on `WSL`, so we are confident this method works. #### Mingw-w64 -One way to install the prerequisites for `git-secret` on Windows is to use +Another way to install the prerequisites for `git-secret` on Windows is to use [Mingw-w64](https://www.mingw-w64.org/) and install the needed packages. By default, the `Mingw-w64` installation will be saved to `C:\msys64`. You'll need to install `make` and probably other tools such as `gnupg`, `make`, `man`, `git`, and `gawk`. -(This list might not be complete). Again we have automated testing of `git-secret` on `WSL` -so we are confident this method works. +(This list might not be complete). #### MSYS and Cygwin -It should also be possible to use `git-secret` with [MSYS](https://www.msys2.org/) -or [Cygwin](https://www.cygwin.com/), and we have gotten _most_ of the way to getting +`git-secret` also works with [MSYS](https://www.msys2.org/) +and [Cygwin](https://www.cygwin.com/), and we have gotten _most_ of the way to getting `git-secret`'s self-tests running on these setups with Windows (see [windows-related issues](https://github.com/sobolevn/git-secret/issues?q=is%3Aissue+is%3Aopen+windows). -If you can help with getting the tests to work on additional platforms, and/or updating -these docs please do! We welcome contributions `git-secret`, and to this documentation -(as well as to other git-secret docs or code). +We welcome contributions to `git-secret` and its documentation . --- @@ -161,7 +158,7 @@ cd git-secret && make build PREFIX="/usr/local" make install ``` -Note that you can change prefix to be any directory you subsequently include in in your `PATH` +Note that you can change `PREFIX` to be any directory you subsequently include in in your `PATH` environment variable. We generally recommend you stick to the the default install locations for simplicity, but if you know what you're doing you are welcome to change it. diff --git a/man/man1/git-secret-add.1 b/man/man1/git-secret-add.1 index 4a3dfcfd405c853f9e3a53e4ef9a93a01ec7763d..53cbb4bd03785f428cc6c546ce129334bf2afb2e 100644 GIT binary patch delta 12 TcmZqUY2%qNi_vJ~>}*y58>R$4 delta 12 TcmZqUY2%qNi_vi7>}*y58=(X} diff --git a/man/man1/git-secret-cat.1 b/man/man1/git-secret-cat.1 index 9cdb04b728192400d21252ca9f756da5353d661b..bbb184b981f6ad78c2eefe3a24d039410d81cf70 100644 GIT binary patch delta 12 TcmX@feUf{^EJmY^v-Ma3Ald|l delta 12 TcmX@feUf{^EJnkPv-Ma3Ak_qf diff --git a/man/man1/git-secret-changes.1 b/man/man1/git-secret-changes.1 index 9ae0a7338fcf10a3cd4fc6190cee36171c068b7f..afc8081183171bccfc69e9a1b4b13afa93544564 100644 GIT binary patch delta 12 Tcmcb@dxdwxJVv99^G(?RA}a*1 delta 12 Tcmcb@dxdwxJVwKf^G(?RA|?c` diff --git a/man/man1/git-secret-clean.1 b/man/man1/git-secret-clean.1 index e5e366915f126827102a25d637ecb57decaee867..b6f6414a9ccabb5c14ebb90bba800940d73e1209 100644 GIT binary patch delta 12 TcmX@deU5v=97dy!a}8MmAz}oU delta 12 TcmX@deU5v=97e;9a}8MmAzcKO diff --git a/man/man1/git-secret-hide.1 b/man/man1/git-secret-hide.1 index ddb78df6f76ff0689f8ae11791a78e6f7b878cfe..165c23e6d6f7fdac7cecde095f079f53b85d9cc7 100644 GIT binary patch delta 12 UcmaDa^Im4cY(}Gvb1w4&04B}_q5uE@ delta 12 UcmaDa^Im4cY(~S4b1w4&04B)=p#T5? diff --git a/man/man1/git-secret-init.1 b/man/man1/git-secret-init.1 index 54c2680887eb406b1ad99e81df6a638b5bce7bfa..8e556dbe9acd9a712b1e59403e1078ae1dc68db1 100644 GIT binary patch delta 12 TcmdnTyN`FmY(}GvbClQsAOi$y delta 12 TcmdnTyN`FmY(~S4bClQsAN~Ys diff --git a/man/man1/git-secret-list.1 b/man/man1/git-secret-list.1 index 207ee9c507428d36cc3c3293302b1123d50e3db1..a44a56d7b6798ee9646eb761c02722f5985bf674 100644 GIT binary patch delta 12 TcmZ3 diff --git a/man/man1/git-secret-remove.1 b/man/man1/git-secret-remove.1 index 5d86dd14b6735b1e4bfd4a6de4285ffa388f4e4b..ecac221bf1b945630481a9e64158644866c4dffc 100644 GIT binary patch delta 12 TcmZ3r<^SD_79qj}s diff --git a/man/man1/git-secret-removeperson.1 b/man/man1/git-secret-removeperson.1 index 0334e0d9f4278baf6fc1d08c8aca37bf9acfab80..e2cbe05ae0d66178aeff2515c78c251ce42b5ec1 100644 GIT binary patch delta 12 UcmZ3;xsY?hVn(BlOa3wg03SF75C8xG delta 12 UcmZ3;xsY?hVn)M_Oa3wg03S024*&oF diff --git a/man/man1/git-secret-reveal.1 b/man/man1/git-secret-reveal.1 index 54fb0e93dc01fcc7286806f12199e1a5deafd75c..4b997b05794551c58192901d4321d5a02978f0e6 100644 GIT binary patch delta 12 TcmZ20x>j_;Tt=gf^Z2;{A0Grw delta 12 TcmZ20x>j_;Tt>r<^Z2;{9~uNq diff --git a/man/man1/git-secret-tell.1 b/man/man1/git-secret-tell.1 index 9ab10f8e66a4a6b361263496f4770b37de93bf55..88a643813898efe60456dcad3e9e41d6c53a5e2c 100644 GIT binary patch delta 12 TcmX>qd{lVCY(}Gvb2K>tAtnTl delta 12 TcmX>qd{lVCY(~S4b2K>tAt3~f diff --git a/man/man1/git-secret-usage.1 b/man/man1/git-secret-usage.1 index f61cbba2cdc026d88db5ca47759b79db5bf2a8b3..92b5de154a40832acb0c0ae9292eeb4cd1fa5ed2 100644 GIT binary patch delta 12 UcmaFM_LgnJ97dy!b1yIf03_oDW&i*H delta 12 UcmaFM_LgnJ97e;9b1yIf03_Z8WdHyG diff --git a/man/man1/git-secret-whoknows.1 b/man/man1/git-secret-whoknows.1 index 5891813c6b197b620a1b0fbd79a35c00639df46b..199771947161b64451bf74c81a49fa6db5d8b3cf 100644 GIT binary patch delta 12 TcmX@kew=;6d`6><3)GnbAb1gh5SEMJV7o{HNf1cU08)ssF^P$&069buf)I)TiGq`0eV+5Je7Aer-SbZs z0WW~Gf(p^l&_*sPD0l%VXpktVXm|o>m_46^Dd=uzX1~ALJ9zZ|$%~hT#=)y+rK|8D z#3A@h01gtV444qPf+TH4+=njp0;ymqQ%E%z9bn+gIA)>^5%1d9%V6Kk&)RQu^UdsH z6Jy3BuTDd7Ek}7wC|=zR3;>)3reXpNQ6a>viyF8ArhU%sr<02_yL)hE!=5gSQ)2~( zcfH_Vsa~qPe#5>i-zDqzWTjz#L@4SEUsPN2OToy z(g=7&4q9mXhyrLfAYZ~j50&OpXpjMT!SznkA^iltg8~(cqG6UOa~Vi&T$D&PBLRgk zQ(;g6*E*fTK13mGmV@&kUkqj>+;|r>`U+`@7)8VgWWimW>L`q54-?WSg_|JG%w(oW zfx<+3=d|5eIkr!0%S=udFR)L#a%=xMtATqEv=ISDWj-V^FoPhe5;Ef+(lnL;8MXfd z=26Zr>CxM@j|JOUS=e^qfBlbBQp3dL@l&CNzV3x5Eg CTvN&b delta 409 zcmYjNy-UMD6eokU##V}0Q9*gQ6vafW)j=Fuv}o~zprD8W4VPCogJOLMhgz_!TWvie(yb>bxv;Yw8hT-jXtQGx>>PcCNDpS=)`vU z_;jzdTeeMcDeUTgpIwp{shvcK84oCzFR3G~AScs!>JKU6x1BVy zEj3KLVpp|@a3>EJ$jB?jL;f1iST-xdv3X5 public_key.txt # armor here makes it ascii +``` + +2. Import this key into your `gpg` keyring (in `~/.gnupg` or similar) by running `gpg --import public_key.txt` -3. Now add this person to your secrets repo by running `git secret tell persons@email.id` +3. 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) -4. Now remove the other user's public key from your personal keyring with `gpg --delete-keys persons@email.id` +4. Now remove the other user's public key from your personal keyring with `gpg --delete-keys their@email.id` 5. 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. @@ -92,9 +97,9 @@ with the changes in your code. One way of doing it is the following: -1. [create a gpg key](#using-gpg) for your CI/CD environment. You can chose any name and email address you want: for instance `MyApp CodeShip ` -if your app is called MyApp and your CI/CD provider is CodeShip. 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. -2. run `gpg --armor --export-secret-key myapp@codeship.com` to get your private key value +1. [create a gpg key](#using-gpg) for your CI/CD environment. You can chose any name and email address you want: for instance `MyApp Example ` +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. +2. run `gpg --armor --export-secret-key myapp@example.com` to get your private key value 3. 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. 4. Then write your Continuous Deployment build script. For instance: @@ -160,8 +165,8 @@ 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, and some versions of gpg -might not work well with keyrings created with newer versions of gpg. +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. @@ -169,7 +174,13 @@ 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. + +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: @@ -182,13 +193,16 @@ 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. +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`. -In particular, this directory contains a keyring with all the 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` -instead use the user's private keys (which probably reside somewhere like ~/.gnupg/) -and which are not in the `.gitsecret/keys` directory. + +`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.