This is not a great place, as the variable will work anywhere,
but I couldn't find a better place to put it.
Also fixes a typo in the service definition.
This project allows you to use various hardware security devices to operate GPG and SSH. Instead of keeping your key on your computer and decrypting it with a passphrase when you want to use it, the key is generated and stored on the device and never reaches your computer. Read more about the design [here](doc/DESIGN.md).
You can do things like sign your emails, git commits, and software packages, manage your passwords (with [pass](https://www.passwordstore.org/) and [gopass](https://www.justwatch.com/gopass/), among others), authenticate web tunnels and file transfers, and more.
- [TREZOR Firmware 1.3.6—GPG Signing, SSH Login Updates and Advanced Transaction Features for Segwit](https://medium.com/@satoshilabs/trezor-firmware-1-3-6-20a7df6e692)
- [TREZOR Firmware 1.3.6—GPG Signing, SSH Login Updates and Advanced Transaction Features for Segwit](https://medium.com/@satoshilabs/trezor-firmware-1-3-6-20a7df6e692)
- [A Step by Step Guide to Securing your SSH Keys with the Ledger Nano S](https://thoughts.t37.net/a-step-by-step-guide-to-securing-your-ssh-keys-with-the-ledger-nano-s-92e58c64a005)
## Installation
Currently [TREZOR One](https://trezor.io/), [TREZOR Model T](https://trezor.io/), [Keepkey](https://www.keepkey.com/), and [Ledger Nano S](https://www.ledgerwallet.com/products/ledger-nano-s) are supported.
See the [following instructions](doc/INSTALL.md) for the
[TREZOR](https://trezor.io/), [Keepkey](https://www.keepkey.com/) and
@ -36,7 +36,7 @@ The `trezor-agent` then instructs SSH to connect to the server. It will then eng
### GPG
### GPG
GPG uses much the same approach as SSH, expect in this it relies on [SLIP-0017 : ECDH using deterministic hierarchy][3] for the mapping to an ECDH key and it maps these to the normal GPG child key infrastructure.
GPG uses much the same approach as SSH, except in this case it relies on [SLIP-0017 : ECDH using deterministic hierarchy][3] for the mapping to an ECDH key and it maps these to the normal GPG child key infrastructure.
Note: Keepkey does not support en-/de-cryption at this time.
Note: Keepkey does not support en-/de-cryption at this time.
There are many different options to install python environment on macOS ([official](https://www.python.org/downloads/mac-osx/), [anaconda](https://conda.io/docs/user-guide/install/macos.html), ..). Most importantly you need `libusb`. Probably the easiest way is via [homebrew](https://brew.sh/)
$ brew install libusb
## Update setuptools and pip
### GPG
Also, update Python packages before starting the installation:
If you intend to use GPG make sure you have GPG installed and up to date. This software requires a GPG version >= 2.1.11.
$ pip install -U setuptools pip
You can verify your installed version by running:
```
$ gpg2 --version | head -n1
gpg (GnuPG) 2.1.15
```
## Check device's firmware version
* Follow this installation guide for [Debian](https://gist.github.com/vt0r/a2f8c0bcb1400131ff51)
* Install GPG for [macOS](https://sourceforge.net/p/gpgosx/docu/Download/)
* Install packages for Ubuntu 16.04 [here](https://launchpad.net/ubuntu/+source/gnupg2)
* Install packages for Linux Mint 18 [here](https://community.linuxmint.com/software/view/gnupg2)
Make sure you are running the latest firmware version on your hardware device.
# 2. Install the TREZOR agent
Currently the following firmware versions are supported:
Make sure that your `udev` rules are configured [correctly](https://doc.satoshilabs.com/trezor-user/settingupchromeonlinux.html#manual-configuration-of-udev-rules).
2. Make sure that your `udev` rules are configured [correctly](https://doc.satoshilabs.com/trezor-user/settingupchromeonlinux.html#manual-configuration-of-udev-rules).
Then, install the latest [trezor_agent](https://pypi.python.org/pypi/trezor_agent) package:
$ pip install trezor_agent
3. Then, install the latest [trezor_agent](https://pypi.python.org/pypi/trezor_agent) package:
Make sure that your `udev` rules are configured [correctly](https://support.keepkey.com/support/solutions/articles/6000037796-keepkey-wallet-is-not-being-recognized-by-linux).
2. Make sure that your `udev` rules are configured [correctly](https://support.keepkey.com/support/solutions/articles/6000037796-keepkey-wallet-is-not-being-recognized-by-linux).
Then, install the latest [keepkey_agent](https://pypi.python.org/pypi/keepkey_agent) package:
Then, install the latest [keepkey_agent](https://pypi.python.org/pypi/keepkey_agent) package:
Make sure that your `udev` rules are configured [correctly](http://support.ledgerwallet.com/knowledge_base/topics/ledger-wallet-is-not-recognized-on-linux).
2. Make sure that your `udev` rules are configured [correctly](https://ledger.zendesk.com/hc/en-us/articles/115005165269-What-if-Ledger-Wallet-is-not-recognized-on-Linux-).
Then, install the latest [ledger_agent](https://pypi.python.org/pypi/ledger_agent) package:
3. Then, install the latest [ledger_agent](https://pypi.python.org/pypi/ledger_agent) package:
In order to use specific device type for GPG indentity creation, use either command:
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).
In order to use specific device type for GPG operations, set the following environment variable to either:
3. Log out and back into your session to ensure your environment is updated everywhere.
```
$ export GNUPGHOME=~/.gnupg/{trezor,ledger}
## 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
You can use GNU Privacy Assistant (GPA) in order to inspect the created keys
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.
and perform signature and decryption operations using:
Git can use GPG to sign and verify commits and tags (see [here](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)):
Git can use GPG to sign and verify commits and tags (see [here](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)):
```
```
$ git config --local commit.gpgsign 1
$ git config --local commit.gpgsign 1
$ git config --local gpg.program $(which gpg2)
$ git config --local gpg.program $(which gpg2)
@ -66,11 +70,29 @@ $ git tag v1.2.3 --sign # create GPG-signed tag
$ git tag v1.2.3 --verify # verify tag signature
$ git tag v1.2.3 --verify # verify tag signature
```
```
## Password manager
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.
First install `pass` from [passwordstore.org](https://www.passwordstore.org/) and initialize it to use your TREZOR-based GPG identity:
### Manage passwords
Password managers such as [pass](https://www.passwordstore.org/) and [gopass](https://www.justwatch.com/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:
```
```
$ export GNUPGHOME=~/.gnupg/trezor
$ pass init "Roman Zeyde <roman.zeyde@gmail.com>"
$ pass init "Roman Zeyde <roman.zeyde@gmail.com>"
Password store initialized for Roman Zeyde <roman.zeyde@gmail.com>
Password store initialized for Roman Zeyde <roman.zeyde@gmail.com>
```
```
@ -99,10 +121,9 @@ Copied VPS/linode to clipboard. Will clear in 45 seconds.
You can also use the following [Qt-based UI](https://qtpass.org/) for `pass`:
You can also use the following [Qt-based UI](https://qtpass.org/) for `pass`:
In order to use the default GPG pinentry program, install one of the following Linux packages:
```
$ apt install pinentry-{curses,gnome3,qt}
```
or (on macOS):
```
$ brew install pinentry
```
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 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.
##### 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.
to start the agent in the background and execute the command with environment variables set up to use the SSH agent. The specified identity is used for all SSH connections. The agent will exit after the command completes.
Note the `--` separator, which is used to separate `trezor-agent`'s arguments from the SSH command arguments.
The identity `user@remotehost` is used as both the destination user and host as well as for key derivation, so you must generate a separate key for each host you connect to.
Add the following configuration to your `~/.ssh/config` file:
2015-09-02 15:09:39,782 INFO getting "ssh://user@ssh.hostname.com" public key from Trezor...
2015-09-02 15:09:44,430 INFO please confirm user "roman" login to "ssh://user@ssh.hostname.com" using Trezor...
2015-09-02 15:09:46,152 INFO signature status: OK
Linux lmde 3.16.0-4-amd64 #1 SMP Debian 3.16.7-ckt11-1+deb8u3 (2015-08-04) x86_64
The programs included with the Debian GNU/Linux system are free software;
Host github.com
the exact distribution terms for each program are described in the
IdentityFile ~/.ssh/github.pub
individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
Use the following Bash alias for convenient Git operations:
permitted by applicable law.
Last login: Tue Sep 1 15:57:05 2015 from localhost
~ $
Make sure to confirm SSH signature on the Trezor device when requested.
$ alias ssh-shell='trezor-agent ~/.ssh/github.pub -v --shell'
## Accessing remote Git/Mercurial repositories
Now, you can use regular Git commands under the "SSH-enabled" sub-shell:
Use your SSH public key to access your remote repository (e.g. [GitHub](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/)):