From 25f066e1135427ece443c16ffba74b2a11efa049 Mon Sep 17 00:00:00 2001 From: rendaw Date: Tue, 13 Mar 2018 05:43:10 +0900 Subject: [PATCH 1/3] Document --pin-entry-binary with usage guide --- README.md | 1 + doc/INSTALL.md | 6 ++++- doc/README-GPG.md | 2 ++ doc/README-PINENTRY.md | 51 ++++++++++++++++++++++++++++++++++++++++++ doc/README-SSH.md | 3 +++ 5 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 doc/README-PINENTRY.md diff --git a/README.md b/README.md index cbe6c9e..8caf4ce 100644 --- a/README.md +++ b/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) \ No newline at end of file diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 447aff3..ff80494 100644 --- a/doc/INSTALL.md +++ b/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: diff --git a/doc/README-GPG.md b/doc/README-GPG.md index dbfe3e7..72574b4 100644 --- a/doc/README-GPG.md +++ b/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). diff --git a/doc/README-PINENTRY.md b/doc/README-PINENTRY.md new file mode 100644 index 0000000..1ce9e66 --- /dev/null +++ b/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 " +``` + +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. \ No newline at end of file diff --git a/doc/README-SSH.md b/doc/README-SSH.md index 48658c1..40e3fea 100644 --- a/doc/README-SSH.md +++ b/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 ```` From a1f7088d33f8e324000a063b0acba735766e0b39 Mon Sep 17 00:00:00 2001 From: rendaw Date: Tue, 13 Mar 2018 05:47:31 +0900 Subject: [PATCH 2/3] Remove pin entry instructions from INSTALL, didn't seem that relevant --- doc/INSTALL.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/doc/INSTALL.md b/doc/INSTALL.md index ff80494..e1d44e7 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -65,10 +65,6 @@ 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 default PIN entry. - - If you'd like a Trezor-style PIN entry program, follow [these instructions](README-PINENTRY.md). - # 3. Install the KeepKey agent 1. Make sure you are running the latest firmware version on your KeepKey: @@ -89,8 +85,6 @@ 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: From 329f07249a991770a117ef44a91c91021dc9e143 Mon Sep 17 00:00:00 2001 From: rendaw Date: Tue, 13 Mar 2018 05:57:39 +0900 Subject: [PATCH 3/3] Small reword --- doc/README-PINENTRY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/README-PINENTRY.md b/doc/README-PINENTRY.md index 1ce9e66..9a0f283 100644 --- a/doc/README-PINENTRY.md +++ b/doc/README-PINENTRY.md @@ -2,7 +2,7 @@ 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. +You can specify a custom PIN entry program such as [trezor-gpg-pinentry-tk](https://github.com/rendaw/trezor-gpg-pinentry-tk) (and separately, a passphrase entry program) to match your workflow. The below examples use `trezor-gpg-pinentry-tk` but any GPG compatible PIN entry can be used.