additional security sanity checks on pairing messages

1 files changed, 27 insertions, 4 deletions

diff --git a/doc/design/assistant/pairing.mdwn b/doc/design/assistant/pairing.mdwn
index 388010ca8..fb4f4dd8f 100644
--- a/doc/design/assistant/pairing.mdwn
+++ b/doc/design/assistant/pairing.mdwn
@@ -3,12 +3,23 @@ have some way of pairing devices.
 
 ## security
 
+Pairing uses its own network protocol, built on top of multicast UDP.
+
 It's important that pairing securely verifies that the right host is being
 paired with. This is accomplied by having a shared secret be entered on
-both the hosts that will be paired. They can then construct messages that
-the other host can verify using the shared secret, and so know that,
-for example, the ssh public key it received belongs to the right host
-and has not been altered by a man in the middle.
+both the hosts that will be paired. Hopefully that secret is communicated
+securely out of band. 
+
+(In practice, the security of that communication will vary. To guard against
+interception, each pairing session pairs exactly two hosts and then forgets
+the shared secret. So an attacker who tries to reuse an intercepted secret
+will not succeed in pairing. This does not guard against an intercepted
+secret that is used before the legitimate parties finish pairing.)
+
+Each host can construct messages that the other host can verify using the
+shared secret, and so know that, for example, the ssh public key it
+received belongs to the right host and has not been altered by a man in the
+middle.
 
 The verification works like this: Take a HMAC SHA1 checksum of the message,
 using the shared secret as the HMAC key. Include this checksum after the
@@ -44,6 +55,18 @@ by replaying these:
 
 So replay attacks don't seem to be a problem.
 
+So far I've considered security from a third-party attacker, but either the
+first or second parties in pairing could also be attackers. Presumably they
+trust each other with access to their files as mediated by
+[[git-annex-shell]]. However, one could try to get shell access to the
+other's computer by sending malicious data in a pairing message. So the
+pairing code always checks every data field's content, for example the ssh
+public key is rejected if it looks at all unusual. Any control characters
+in the pairing message cause it to be rejected, to guard against console
+poisoning attacks. Furthermore, git-annex is careful not to expose data to
+the shell, and the webapp uses Yesod's type safety to ensure all user input
+is escaped before going to the browser.
+
 ## TODO
 
 * pairing over IPV6 only networks does not work. Haskell's