Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add pass to GPG walkthrough documentation #79

Merged
merged 2 commits into from
Oct 25, 2021
Merged

Add pass to GPG walkthrough documentation #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a8be8f
chore: minor fix to README
smlx Oct 25, 2021
47c8d0e
chore: update docs and fix broken links
smlx Oct 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!

Expand Down
36 changes: 27 additions & 9 deletions docs/content/en/docs/gpg-walkthrough.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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!
```
4 changes: 2 additions & 2 deletions docs/content/en/docs/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" %}}
Expand Down Expand Up @@ -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.