Merge branch 'master' into neopg-wip

doc/DESIGN.md

@@ -12,11 +12,11 @@ So when you `ssh` to a machine - rather than consult the normal ssh-agent (which
 
 ## Key Naming
 
-`trezor-agent` goes to great length to avoid using the valuable parent key. 
+`trezor-agent` goes to great length to avoid using the valuable parent key.
 
-The rationale behind this is that `trezor-agent` is to some extent condemned to *blindly* signing any NONCE given to it (e.g. as part of a challenge respone, or as the hash/hmac of someting to sign). 
+The rationale behind this is that `trezor-agent` is to some extent condemned to *blindly* signing any NONCE given to it (e.g. as part of a challenge respone, or as the hash/hmac of someting to sign).
 
-And doing so with the master private key is risky - as rogue (ssh) server could possibly provide a doctored NONCE that happens to be tied to a transaction or something else. 
+And doing so with the master private key is risky - as rogue (ssh) server could possibly provide a doctored NONCE that happens to be tied to a transaction or something else.
 
 It therefore uses only derived child keys pairs instead (according to the [BIP-0032: Hierarchical Deterministic Wallets][1] system) - and ones on different leafs. So the parent key is only used within the device for creating the child keys - and not exposed in any way to `trezor-agent`.
 
@@ -26,7 +26,7 @@ It is common for SSH users to use one (or a few) private keys with SSH on all se
 
 So taking a commmand such as:
 
-	$ trezor-agent -c user@fqdn.com 
+	$ trezor-agent -c user@fqdn.com
 
 The `trezor-agent` will take the `user`@`fqdn.com`; canonicalise it (e.g. to add the ssh default port number if none was specified) and then apply some simple hashing (See [SLIP-0013 : Authentication using deterministic hierarchy][2]). The resulting 128bit hash is then used to construct a lead 'HD node' that contains an extened public private *child* key.
 
@@ -42,10 +42,10 @@ Note: Keepkey does not support en-/de-cryption at this time.
 
 ### Index
 
-The canonicalisation process ([SLIP-0013][2] and [SLIP-0017][3]) of an email address or ssh address allows for the mixing in of an extra 'index' - a unsigned 32 bit number. This allows one to have multiple, different keys, for the same address. 
+The canonicalisation process ([SLIP-0013][2] and [SLIP-0017][3]) of an email address or ssh address allows for the mixing in of an extra 'index' - a unsigned 32 bit number. This allows one to have multiple, different keys, for the same address.
 
 This feature is currently not used -- it is set to '0'. This may change in the future.
 
-[1]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki 
+[1]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
 [2]: https://github.com/satoshilabs/slips/blob/master/slip-0013.md
 [3]: https://github.com/satoshilabs/slips/blob/master/slip-0017.md

doc/INSTALL.md

@@ -21,7 +21,7 @@ You can install them on these distributions as follows:
 
 ##### Fedora
 
-    $ dnf install python3-pip python3-devel python3-tk libusb-devel libudev-devel \
+    $ dnf install python3-pip python3-devel python3-tkinter libusb-devel libudev-devel \
                   gcc redhat-rpm-config
 
 ##### OpenSUSE
@@ -33,7 +33,7 @@ If you are using python3 or your system `pip` command points to `pip3.x`
 dependencies instead:
 
     $ zypper install python3-pip python3-devel python3-tk libusb-1_0-devel libudev-devel
-    
+
 ##### macOS
 
 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/)
@@ -77,6 +77,12 @@ gpg (GnuPG) 2.1.15
     $ pip3 install --user -e trezor-agent/agents/trezor
     ```
 
+    Or, through Homebrew on macOS:
+
+    ```
+    $ brew install trezor-agent
+    ```
+
 # 3. Install the KeepKey agent
 
 1. Make sure you are running the latest firmware version on your KeepKey:
@@ -90,6 +96,12 @@ Then, install the latest [keepkey_agent](https://pypi.python.org/pypi/keepkey_ag
     $ pip3 install keepkey_agent
     ```
 
+    Or, on Mac using Homebrew:
+
+    ```
+    $ homebrew install keepkey-agent
+    ```
+
     Or, directly from the latest source code:
 
     ```

doc/README-GPG.md

@@ -70,6 +70,21 @@ $ 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](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.

doc/README-PINENTRY.md

@@ -9,7 +9,7 @@ $ apt install pinentry-{curses,gnome3,qt}
 or (on macOS):
 
 ```
-$ brew install pinentry-mac
+$ 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.

doc/README-SSH.md

@@ -32,6 +32,7 @@ $ (trezor|keepkey|ledger)-agent identity@myhost -- COMMAND --WITH --ARGUMENTS
 ```
 
 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.
 
 As a shortcut you can run
 
@@ -161,7 +162,7 @@ export SSH_AUTH_SOCK=$(systemctl show --user --property=Listen trezor-ssh-agent.
 If SSH connection fails to work, please open an [issue](https://github.com/romanz/trezor-agent/issues)
 with a verbose log attached (by running `trezor-agent -vv`) .
 
-##### Incompatible SSH options
+##### `IdentitiesOnly` SSH option
 
 Note that your local SSH configuration may ignore `trezor-agent`, if it has `IdentitiesOnly` option set to `yes`.
 
@@ -172,6 +173,21 @@ Note that your local SSH configuration may ignore `trezor-agent`, if it has `Ide
              This option is intended for situations where ssh-agent offers many different identities.
              The default is “no”.
 
-If you are failing to connect, try running:
+If you are failing to connect, save your public key using:
 
-    $ trezor-agent -vv user@host -- ssh -vv -oIdentitiesOnly=no user@host
+	$ trezor-agent -vv foobar@hostname.com > ~/.ssh/hostname.pub
+
+And add the following lines to `~/.ssh/config` (providing the public key explicitly to SSH):
+
+	Host hostname.com
+		User foobar
+		IdentityFile ~/.ssh/hostname.pub
+
+Then, the following commands should successfully command to the remote host:
+
+	$ trezor-agent -v foobar@hostname.com -s
+	$ ssh foobar@hostname.com
+
+or,
+
+	$ trezor-agent -v foobar@hostname.com -c