Document --pin-entry-binary with usage guide

README.md

@@ -23,3 +23,4 @@ Currently [TREZOR One](https://trezor.io/), [TREZOR Model T](https://trezor.io/)
     Note: If you're using Windows, see [trezor-ssh-agent](https://github.com/martin-lizner/trezor-ssh-agent) by Martin Lízner.
 
 * **GPG** instructions and common use cases are [here](doc/README-GPG.md)
+* Instructions to configure a Trezor-style **PIN entry** program are [here](doc/README-PINENTRY.md)

doc/INSTALL.md

@@ -65,7 +65,9 @@ gpg (GnuPG) 2.1.15
     $ pip3 install --user -e trezor-agent/agents/trezor
     ```
 
-    Read [these instructions](https://github.com/romanz/python-trezor#pin-entering) on how to enter your PIN with the PIN entry.
+    Read [these instructions](https://github.com/romanz/python-trezor#pin-entering) on how to enter your PIN with the default PIN entry.
+
+    If you'd like a Trezor-style PIN entry program, follow [these instructions](README-PINENTRY.md).
 
 # 3. Install the KeepKey agent
 
@@ -87,6 +89,8 @@ Then, install the latest [keepkey_agent](https://pypi.python.org/pypi/keepkey_ag
     $ pip3 install --user -e trezor-agent/agents/keepkey
     ```
 
+    Read [these instructions](https://github.com/romanz/python-trezor#pin-entering) on how to enter your PIN with the default PIN entry.
+
 # 4. Install the Ledger Nano S agent
 
 1. Make sure you are running the latest firmware version on your Ledger Nano S:

doc/README-GPG.md

@@ -23,6 +23,8 @@ Thanks!
 
     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](README-PINENTRY.md).
+
 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).

doc/README-PINENTRY.md

@@ -0,0 +1,51 @@
+# Custom PIN entry
+
+By default a standard GPG PIN entry program is used when entering your Trezor PIN, but it's difficult to use if you don't have a numeric keypad or want to use your mouse.
+
+You can specify a custom PIN entry program (and separately, a passphrase entry program) such as [trezor-gpg-pinentry-tk](https://github.com/rendaw/trezor-gpg-pinentry-tk) to match your workflow.
+
+The below examples use `trezor-gpg-pinentry-tk` but any GPG compatible PIN entry can be used.
+
+##### 1. Install the PIN entry
+
+Run
+
+```
+pip install trezor-gpg-pinentry-tk
+```
+
+##### 2. SSH
+
+Add the flag `--pin-entry-binary trezor-gpg-pinentry-tk` to all calls to `trezor-agent`.
+
+To automatically use this flag, add the line `pinentry=trezor-gpg-pinentry-tk` to `~/.ssh/agent.config`.  **Note** this is currently broken due to [this dependency issue](https://github.com/bw2/ConfigArgParse/issues/114).
+
+If you run the SSH agent with Systemd you'll need to add `--pin-entry-binary` to the `ExecStart` command.  You may also need to add this line:
+
+```
+Environment="DISPLAY=:0"
+```
+
+to the `[Service]` section to tell the PIN entry program how to connect to the X11 server.
+
+##### 3. GPG
+
+If you haven't completed initialization yet, run:
+
+```
+$ (trezor|keepkey|ledger)-gpg init --pin-entry-binary trezor-gpg-pinentry-tk "Roman Zeyde <roman.zeyde@gmail.com>"
+```
+
+to configure the PIN entry at the same time.
+
+Otherwise, open `$GNUPGHOME/trezor/run-agent.sh` and change the `--pin-entry-binary` option to `trezor-gpg-pinentry-tk` and run:
+
+```
+killall trezor-gpg-agent
+```
+
+##### 4. Troubleshooting
+
+Any problems running the PIN entry program with GPG should appear in `$HOME/.gnupg/trezor/gpg-agent.log`.
+
+You can get similar logs for SSH by specifying `--log-file` in the SSH command line.

doc/README-SSH.md

@@ -6,6 +6,8 @@ SSH requires no configuration, but you may put common command line options in `~
 
 See `(trezor|keepkey|ledger)-agent -h` for details on supported options and the configuration file format.
 
+If you'd like a Trezor-style PIN entry program, follow [these instructions](README-PINENTRY.md).
+
 ## 2. Usage
 
 Use the `(trezor|keepkey|ledger)-agent` program to work with SSH. It has three main modes of operation:
@@ -113,6 +115,7 @@ Requires=trezor-ssh-agent.socket
 
 [Service]
 Type=Simple
+Environment="PATH=/bin:/usr/bin:/usr/local/bin:%h/.local/bin"
 ExecStart=/usr/bin/trezor-agent --foreground --sock-path %t/trezor-agent/S.ssh IDENTITY
 ````