Merge pull request #79 from smlx/pass-walkthrough

Add pass to GPG walkthrough documentation

README.md

@@ -7,7 +7,7 @@
 
 ## About
 
-* `piv-agent` is an SSH and GPG agent providing simple integration of [PIV](https://csrc.nist.gov/projects/piv/piv-standards-and-supporting-documentation) hardware (e.g. a [Yubikey](https://developers.yubico.com/yubico-piv-tool/YubiKey_PIV_introduction.html)) with `ssh` and `gpg` workflows such as [`git`](https://git-scm.com/) signing, [`pass`](https://www.passwordstore.org/) encryption, or [keybase](https://keybase.io/) chat.
+* `piv-agent` is an SSH and GPG agent providing simple integration of [PIV](https://csrc.nist.gov/projects/piv/piv-standards-and-supporting-documentation) hardware (e.g. a [Yubikey](https://developers.yubico.com/yubico-piv-tool/YubiKey_PIV_introduction.html)) with `ssh`, and `gpg` workflows such as [`git`](https://git-scm.com/) signing, [`pass`](https://www.passwordstore.org/) encryption, or [keybase](https://keybase.io/) chat.
 * `piv-agent` originated as a reimplementation of [yubikey-agent](https://github.com/FiloSottile/yubikey-agent) because I needed some extra features, and also to gain a better understanding of the PIV applet on security key hardware.
 * `piv-agent` makes heavy use of the Go standard library and supplementary `crypto` packages, as well as [`piv-go`](https://github.com/go-piv/piv-go/) and [`pcsclite`](https://pcsclite.apdu.fr/). Thanks for the great software!
 

docs/content/en/docs/gpg-walkthrough.md

@@ -11,7 +11,7 @@ This example is intended to illustrate how `piv-agent` can integrate with existi
 
 {{% alert title="Note" %}}
 This example requires switching between `gpg-agent` and `piv-agent`.
-See the [FAQ](/docs/faq) for how to do that.
+See the [FAQ](../../docs/faq) for how to do that.
 {{% /alert %}}
 
 ## Setup
@@ -397,14 +397,6 @@ The subkey with the most recent date is preferred by `gpg`.
 
 Importantly the master key ID is the same after adding the subkeys, so any existing workflows will continue to work as before.
 
-```
-# example ~/.config/git/config
-[user]
-	name = Scott Leggett
-	email = scott@sl.id.au
-	signingKey = 9FA216008BDF1AE5E1BCAEC3EC26B2E4240DD2A9
-```
-
 ### Publish public key
 
 The public key can now be distributed to keyservers and other services such as Github.
@@ -547,3 +539,29 @@ gpg: AES256 encrypted data
 gpg: original file name='foo'
 bar
 ```
+
+### Common software integration
+
+#### git
+
+The same master key ID will work as before, but signing will prefer to use the hardware security device if it is plugged in.
+
+```
+# example ~/.config/git/config
+[user]
+	name = Scott Leggett
+	email = scott@sl.id.au
+	signingKey = 9FA216008BDF1AE5E1BCAEC3EC26B2E4240DD2A9
+[commit]
+	gpgSign = true
+```
+
+#### pass
+
+`pass` has the ability to encrypt to multiple key-ids.
+Running `pass init` will re-encrypt existing passwords and configure `pass` to use the specified key-ids for encryption.
+As usual, `piv-agent` will use the cryptographic key stored in hardware for decryption if it is available, but fall back to the keyfile otherwise.
+
+```
+pass init 0x42B99C3339C9FBC1! 0x84F7BF2FEAC32674!
+```

docs/content/en/docs/setup.md

@@ -76,7 +76,7 @@ Private GPG keys to be used by `piv-agent` must be exported to the directory `~/
 
 {{% alert title="Note" %}}
 This step requires `gpg-agent` to be running, not `piv-agent`.
-See the [FAQ](/docs/faq) for how to switch between the two services.
+See the [FAQ](../../docs/faq) for how to switch between the two services.
 {{% /alert %}}
 
 {{% alert title="Note" %}}
@@ -141,4 +141,4 @@ Adding a subkey requires cross-signing between the master key and sub key, so yo
 
 `gpg` will choose the _newest_ available subkey to perform an action. So it will automatically prefer a newly added `piv-agent` subkey over any existing keyfile subkeys, but fall back to keyfiles if e.g. the Yubikey is not plugged in.
 
-See the [GPG Walkthrough](/docs/gpg-walkthrough) for an example of this procedure.
+See the [GPG Walkthrough](../../docs/gpg-walkthrough) for an example of this procedure.