trezor-agent/doc/README-GPG.md

GPG Agent

Note: the GPG-related code is still under development, so please try the current implementation and please let me know if something doesn't work well for you. If possible:

• record the session (e.g. using asciinema)
• attach the GPG agent log from ~/.gnupg/{trezor,ledger}/gpg-agent.log (can be encrypted)

Thanks!

1. Configuration

1. Initialize the agent GPG directory.

   

   Run

   $ (trezor|keepkey|ledger)-gpg init "Roman Zeyde <roman.zeyde@gmail.com>"
   

   Follow the instructions provided to complete the setup. Keep note of the timestamp value which you'll need if you want to regenerate the key later.

   If you'd like a Trezor-style PIN entry program, follow these instructions.

2. Add export GNUPGHOME=~/.gnupg/(trezor|keepkey|ledger) to your .bashrc or other environment file.

   This GNUPGHOME contains your hardware keyring and agent settings. This agent software assumes all keys are backed by hardware devices so you can't use standard GPG keys in GNUPGHOME (if you do mix keys you'll receive an error when you attempt to use them).

   If you wish to switch back to your software keys unset GNUPGHOME.

3. Log out and back into your session to ensure your environment is updated everywhere.

2. Usage

You can use any GPG commands or software that uses GPG as usual and will be prompted to interact with your hardware device as necessary. The agent is automatically started if it isn't running when you run any gpg command.

Restarting the agent

If you change settings or need to restart the agent for some other reason, simply kill it. It will restart the next time GPG is invoked.

3. Common Use Cases

Sign and decrypt files

Inspect GPG keys

You can use GNU Privacy Assistant (GPA) in order to inspect the created keys and perform signature and decryption operations as usual:

$ sudo apt install gpa
$ gpa

Sign Git commits and tags

Git can use GPG to sign and verify commits and tags (see here):

$ git config --local commit.gpgsign 1
$ git config --local gpg.program $(which gpg2)
$ git commit --gpg-sign                      # create GPG-signed commit
$ git log --show-signature -1                # verify commit signature
$ git tag v1.2.3 --sign                      # create GPG-signed tag
$ git tag v1.2.3 --verify                    # verify tag signature

Note that your git email has to correlate to your gpg key email. If you use a different email for git, you'll need to either generate a new gpg key for that email or set your git email using the command:

$ git config  user.email foo@example.com

If your git email is configured incorrectly, you will receive the error:

error: gpg failed to sign the data
fatal: failed to write commit object

when committing to git.

Manage passwords

Password managers such as pass and gopass rely on GPG for encryption so you can use your device with them too.

With pass:

First install pass from [passwordstore.org] and initialize it to use your TREZOR-based GPG identity:

$ pass init "Roman Zeyde <roman.zeyde@gmail.com>"
Password store initialized for Roman Zeyde <roman.zeyde@gmail.com>

Then, you can generate truly random passwords and save them encrypted using your public key (as separate .gpg files under ~/.password-store/):

$ pass generate Dev/github 32
$ pass generate Social/hackernews 32
$ pass generate Social/twitter 32
$ pass generate VPS/linode 32
$ pass
Password Store
├── Dev
│   └── github
├── Social
│   ├── hackernews
│   └── twitter
└── VPS
    └── linode

In order to paste them into the browser, you'd need to decrypt the password using your hardware device:

$ pass --clip VPS/linode
Copied VPS/linode to clipboard. Will clear in 45 seconds.

You can also use the following Qt-based UI for pass:

$ sudo apt install qtpass

Re-generate a GPG identity

If you've forgotten the timestamp value, but still have access to the public key, then you can retrieve the timestamp with the following command (substitute "john@doe.bit" for the key's address or id):

$ gpg2 --export 'john@doe.bit' | gpg2 --list-packets | grep created | head -n1

Add new UIDs to your identity

After your main identity is created, you can add new user IDs using the regular GnuPG commands:

$ trezor-gpg init "Foobar" -vv
$ export GNUPGHOME=${HOME}/.gnupg/trezor
$ gpg2 -K
------------------------------------------
sec   nistp256/6275E7DA 2017-12-05 [SC]
uid         [ultimate] Foobar
ssb   nistp256/35F58F26 2017-12-05 [E]

$ gpg2 --edit Foobar
gpg> adduid
Real name: Xyzzy
Email address:
Comment:
You selected this USER-ID:
    "Xyzzy"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o

gpg> save

$ gpg2 -K
------------------------------------------
sec   nistp256/6275E7DA 2017-12-05 [SC]
uid         [ultimate] Xyzzy
uid         [ultimate] Foobar
ssb   nistp256/35F58F26 2017-12-05 [E]

Generate GnuPG subkeys

In order to add TREZOR-based subkey to an existing GnuPG identity, use the --subkey flag:

$ gpg2 -k foobar
pub   rsa2048/90C4064B 2017-10-10 [SC]
uid         [ultimate] foobar
sub   rsa2048/4DD05FF0 2017-10-10 [E]

$ trezor-gpg init "foobar" --subkey

In order to enter existing GPG passphrase, I recommend installing and using a graphical Pinentry:

$ sudo apt install pinentry-gnome3
$ sudo update-alternatives --config pinentry
There are 4 choices for the alternative pinentry (providing /usr/bin/pinentry).

  Selection    Path                      Priority   Status
------------------------------------------------------------
* 0            /usr/bin/pinentry-gnome3   90        auto mode
  1            /usr/bin/pinentry-curses   50        manual mode
  2            /usr/bin/pinentry-gnome3   90        manual mode
  3            /usr/bin/pinentry-qt       80        manual mode
  4            /usr/bin/pinentry-tty      30        manual mode

Press <enter> to keep the current choice[*], or type selection number: 0

Sign and decrypt email

Follow these instructions to set up Enigmail in Thunderbird.

Start the agent as a systemd unit

1. Create these files in ~/.config/systemd/user

Replace trezor with keepkey or ledger as required.

trezor-gpg-agent.service

[Unit]
Description=trezor-gpg-agent
Requires=trezor-gpg-agent.socket

[Service]
Type=Simple
Environment="GNUPGHOME=%h/.gnupg/trezor"
Environment="PATH=/bin:/usr/bin:/usr/local/bin:%h/.local/bin"
ExecStart=/usr/bin/trezor-gpg-agent -vv

If you've installed trezor-agent locally you may have to change the path in ExecStart=.

trezor-gpg-agent.socket

[Unit]
Description=trezor-gpg-agent socket

[Socket]
ListenStream=%t/gnupg/S.gpg-agent
FileDescriptorName=std
SocketMode=0600
DirectoryMode=0700

[Install]
WantedBy=sockets.target

2. Stop trezor-gpg-agent if it's already running

killall trezor-gpg-agent

3. Run

systemctl --user start trezor-gpg-agent.service trezor-gpg-agent.socket
systemctl --user enable trezor-gpg-agent.socket