From b3f6e39b48ef85650a63b84b7c0545c259b4fa0a Mon Sep 17 00:00:00 2001 From: Dirk-Willem van Gulik Date: Wed, 15 Nov 2017 19:53:23 +0100 Subject: [PATCH 1/6] First cut at a design rationale --- doc/DESIGN.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 doc/DESIGN.md diff --git a/doc/DESIGN.md b/doc/DESIGN.md new file mode 100644 index 0000000..232b558 --- /dev/null +++ b/doc/DESIGN.md @@ -0,0 +1,46 @@ +# Design + +Most cryptographic tools (such as gpg, ssh and openssl) allow the offloading of some key cryptographic steps to *engines* or *agents*. This is to allow sensitive operations, such as asking for a password or doing the actual encryption step, to be kept separate from the larger body of code. This makes it easier to secure those steps, move them onto hardware or easier to audit. + +The various hardware wallets (Trezor, KeepKey and Ledger) each have the ability (as of Firmware 1.3.4) to use the NIST P-256 elliptic curve to sign, encrypt or decrypt. This curve can be used with S/MIME, GPG and SSH. + +SSH and GPG do this by means of a simple chatty ASCII interprocess communication protocol (usually a unix domain socket) and an agent (`ssh-agent`) or GPG key deamon (`gpg-agent`). + +These two agents make the connection between the front end (e.g. a `gpg --sign` command, or an `ssh user@fqdn`). And then they wait for a request from the `front end', and then do the actual asking for a password and subsequent using the private key to sign or decrypt something. + +The `trezor-agent` mimics these two protocols. + +So when you `ssh` to a machine - rather than consult the normal ssh-agent (which in turn will use your private SSH key in files such as `~/.ssh/id_rsa`) -- the trezor-agent will aks your hardware wallet to use its private key to sign the challenge. + +## Key Naming + +`trezor-agent' goes to some length to avoid using the valuable parent key. It uses derived child keys pairs instead (according to the [BIP-0032: Hierarchical Deterministic Wallets][1] system). Part of the rationale behind this is that `trezor-agent` is to some extend condemmed 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. + + +### SSH + +It is common for SSH users to use one (or a few) private keys with SSH on all servers they log into. The `trezor-agent` is slightly more cautious and derives a child key that is *unique* to the server and username you are logging into from your master private key on the device. + +So taking a commmand such as: + + $ 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. + +This way they keypair is specific to the server/hostname/port and protocol combination used. And it is this private key that is used to sign the nonce passed by the SSH server (as opposed to the master key). + +The `trezor-agent` then instructs SSH to connect to the server. It will then engage in the normal challenge response process, ask the hardware wallet to blindly sign any nonce flashed by the server with the derived child private key and return this to the server. It then hands over to normal SSH for the rest of the logged in session. + +### 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 signing key and it maps these to the normal GPG child key infrastructure. + +### Index + +The canonicalisation process ([SLIP-0013][2] and [SLIP-0071][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 +[2]: https://github.com/satoshilabs/slips/blob/master/slip-0013.md +[3]: https://github.com/satoshilabs/slips/blob/master/slip-0017.md From 1906e6d9b00c6fd7b40d7233daa9195b22cc66ca Mon Sep 17 00:00:00 2001 From: Dirk-Willem van Gulik Date: Wed, 15 Nov 2017 19:56:10 +0100 Subject: [PATCH 2/6] Rework order of paragraphs for clarity. --- doc/DESIGN.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 232b558..efdb876 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -2,19 +2,18 @@ Most cryptographic tools (such as gpg, ssh and openssl) allow the offloading of some key cryptographic steps to *engines* or *agents*. This is to allow sensitive operations, such as asking for a password or doing the actual encryption step, to be kept separate from the larger body of code. This makes it easier to secure those steps, move them onto hardware or easier to audit. +These two agents make the connection between the front end (e.g. a `gpg --sign` command, or an `ssh user@fqdn`). And then they wait for a request from the `front end', and then do the actual asking for a password and subsequent using the private key to sign or decrypt something. + The various hardware wallets (Trezor, KeepKey and Ledger) each have the ability (as of Firmware 1.3.4) to use the NIST P-256 elliptic curve to sign, encrypt or decrypt. This curve can be used with S/MIME, GPG and SSH. SSH and GPG do this by means of a simple chatty ASCII interprocess communication protocol (usually a unix domain socket) and an agent (`ssh-agent`) or GPG key deamon (`gpg-agent`). - -These two agents make the connection between the front end (e.g. a `gpg --sign` command, or an `ssh user@fqdn`). And then they wait for a request from the `front end', and then do the actual asking for a password and subsequent using the private key to sign or decrypt something. - The `trezor-agent` mimics these two protocols. So when you `ssh` to a machine - rather than consult the normal ssh-agent (which in turn will use your private SSH key in files such as `~/.ssh/id_rsa`) -- the trezor-agent will aks your hardware wallet to use its private key to sign the challenge. ## Key Naming -`trezor-agent' goes to some length to avoid using the valuable parent key. It uses derived child keys pairs instead (according to the [BIP-0032: Hierarchical Deterministic Wallets][1] system). Part of the rationale behind this is that `trezor-agent` is to some extend condemmed 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. +`trezor-agent` goes to some length to avoid using the valuable parent key. It uses derived child keys pairs instead (according to the [BIP-0032: Hierarchical Deterministic Wallets][1] system). Part of the rationale behind this is that `trezor-agent` is to some extend condemmed 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. ### SSH From 2b51a85c262760c80a4ecf2c090b9d5663467daa Mon Sep 17 00:00:00 2001 From: Dirk-Willem van Gulik Date: Wed, 15 Nov 2017 19:57:09 +0100 Subject: [PATCH 3/6] Rework order of paragraphs for clarity II --- doc/DESIGN.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index efdb876..ccf8eef 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -2,13 +2,12 @@ Most cryptographic tools (such as gpg, ssh and openssl) allow the offloading of some key cryptographic steps to *engines* or *agents*. This is to allow sensitive operations, such as asking for a password or doing the actual encryption step, to be kept separate from the larger body of code. This makes it easier to secure those steps, move them onto hardware or easier to audit. +SSH and GPG do this by means of a simple chatty ASCII interprocess communication protocol (usually a unix domain socket) and an agent (`ssh-agent`) or GPG key deamon (`gpg-agent`). The `trezor-agent` mimics these two protocols. + These two agents make the connection between the front end (e.g. a `gpg --sign` command, or an `ssh user@fqdn`). And then they wait for a request from the `front end', and then do the actual asking for a password and subsequent using the private key to sign or decrypt something. The various hardware wallets (Trezor, KeepKey and Ledger) each have the ability (as of Firmware 1.3.4) to use the NIST P-256 elliptic curve to sign, encrypt or decrypt. This curve can be used with S/MIME, GPG and SSH. -SSH and GPG do this by means of a simple chatty ASCII interprocess communication protocol (usually a unix domain socket) and an agent (`ssh-agent`) or GPG key deamon (`gpg-agent`). -The `trezor-agent` mimics these two protocols. - So when you `ssh` to a machine - rather than consult the normal ssh-agent (which in turn will use your private SSH key in files such as `~/.ssh/id_rsa`) -- the trezor-agent will aks your hardware wallet to use its private key to sign the challenge. ## Key Naming From b26a4cc7b0ba6251b9e3bfcf2835cac9617935d7 Mon Sep 17 00:00:00 2001 From: Roman Zeyde Date: Thu, 16 Nov 2017 23:01:30 +0200 Subject: [PATCH 4/6] A few small fixes --- doc/DESIGN.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index ccf8eef..1524347 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -2,7 +2,7 @@ Most cryptographic tools (such as gpg, ssh and openssl) allow the offloading of some key cryptographic steps to *engines* or *agents*. This is to allow sensitive operations, such as asking for a password or doing the actual encryption step, to be kept separate from the larger body of code. This makes it easier to secure those steps, move them onto hardware or easier to audit. -SSH and GPG do this by means of a simple chatty ASCII interprocess communication protocol (usually a unix domain socket) and an agent (`ssh-agent`) or GPG key deamon (`gpg-agent`). The `trezor-agent` mimics these two protocols. +SSH and GPG do this by means of a simple interprocess communication protocol (usually a unix domain socket) and an agent (`ssh-agent`) or GPG key daemon (`gpg-agent`). The `trezor-agent` mimics these two protocols. These two agents make the connection between the front end (e.g. a `gpg --sign` command, or an `ssh user@fqdn`). And then they wait for a request from the `front end', and then do the actual asking for a password and subsequent using the private key to sign or decrypt something. @@ -31,11 +31,11 @@ The `trezor-agent` then instructs SSH to connect to the server. It will then eng ### 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 signing key and it maps these to the normal GPG child key infrastructure. +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 decryption key and it maps these to the normal GPG child key infrastructure. ### Index -The canonicalisation process ([SLIP-0013][2] and [SLIP-0071][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. From f2e52a88be2a6142a84abe985e83791c9b86351c Mon Sep 17 00:00:00 2001 From: Roman Zeyde Date: Thu, 16 Nov 2017 23:04:12 +0200 Subject: [PATCH 5/6] ` -> ' --- doc/DESIGN.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 1524347..c22d57a 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -4,7 +4,7 @@ Most cryptographic tools (such as gpg, ssh and openssl) allow the offloading of SSH and GPG do this by means of a simple interprocess communication protocol (usually a unix domain socket) and an agent (`ssh-agent`) or GPG key daemon (`gpg-agent`). The `trezor-agent` mimics these two protocols. -These two agents make the connection between the front end (e.g. a `gpg --sign` command, or an `ssh user@fqdn`). And then they wait for a request from the `front end', and then do the actual asking for a password and subsequent using the private key to sign or decrypt something. +These two agents make the connection between the front end (e.g. a `gpg --sign` command, or an `ssh user@fqdn`). And then they wait for a request from the 'front end', and then do the actual asking for a password and subsequent using the private key to sign or decrypt something. The various hardware wallets (Trezor, KeepKey and Ledger) each have the ability (as of Firmware 1.3.4) to use the NIST P-256 elliptic curve to sign, encrypt or decrypt. This curve can be used with S/MIME, GPG and SSH. @@ -23,7 +23,7 @@ So taking a commmand such as: $ 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. +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. This way they keypair is specific to the server/hostname/port and protocol combination used. And it is this private key that is used to sign the nonce passed by the SSH server (as opposed to the master key). @@ -35,9 +35,9 @@ GPG uses much the same approach as SSH, expect in this it relies on [SLIP-0017 : ### 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. +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 [2]: https://github.com/satoshilabs/slips/blob/master/slip-0013.md From 8b4850b0ce08eeb33145116d09916ce6c4c0fa3e Mon Sep 17 00:00:00 2001 From: Roman Zeyde Date: Thu, 16 Nov 2017 23:01:30 +0200 Subject: [PATCH 6/6] Explain rationale better, several typos fixed, include warning about keepkey not yet supporting encryption/decryption. --- doc/DESIGN.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index c22d57a..28bc064 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -12,8 +12,13 @@ So when you `ssh` to a machine - rather than consult the normal ssh-agent (which ## Key Naming -`trezor-agent` goes to some length to avoid using the valuable parent key. It uses derived child keys pairs instead (according to the [BIP-0032: Hierarchical Deterministic Wallets][1] system). Part of the rationale behind this is that `trezor-agent` is to some extend condemmed 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. +`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). + +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`. ### SSH @@ -31,7 +36,9 @@ The `trezor-agent` then instructs SSH to connect to the server. It will then eng ### 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 decryption key and it maps these to the normal GPG child key infrastructure. +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. + +Note: Keepkey does not support en-/de-cryption at this time. ### Index