add xmpp page

1 files changed, 70 insertions, 0 deletions

diff --git a/doc/design/assistant/xmpp.mdwn b/doc/design/assistant/xmpp.mdwn
new file mode 100644
index 000000000..6d5384e43
--- /dev/null
+++ b/doc/design/assistant/xmpp.mdwn
@@ -0,0 +1,70 @@
+The git-annex assistant uses XMPP to communicate between peers that
+cannot directly talk to one-another. A typical scenario is two users
+who share a repository, that is stored in the [[cloud]].
+
+### TODO
+
+* test with big servers, eg google chat
+* Prevent idle disconnection. Probably means sending or receiving pings,
+  but would prefer to avoid eg pinging every 60 seconds as some clients do.
+* Make the git-annex clients invisible, so a user can use their regular
+  account without always seeming to be present when git-annex is logged in.
+  See <http://xmpp.org/extensions/xep-0126.html>
+* webapp configuration
+* After pulling from a remote, may need to scan for transfers, which
+  could involve other remotes (ie, S3). Since the remote client is not able to
+  talk to us directly, it won't be able to upload any new files to us.
+  Need a fast way to find new files, and get them transferring. The expensive
+  transfer scan may be needed to get fully in sync, but is too expensive to
+  run every time this happens.
+
+## design goals
+
+1. Avoid user-visible messages. dvcs-autosync uses XMPP similarly, but
+   sends user-visible messages. Avoiding user-visible messages lets
+   the user configure git-annex to use his existing XMPP account
+   (eg, Google Talk).
+
+2. Send notifications to buddies. dvcs-autosync sends only self-messages,
+   but that requires every node have the same XMPP account configured.
+   git-annex should support that mode, but it should also send notifications
+   to a user's buddies. (This will also allow for using XMPP for pairing
+   in the future.)
+
+3. Don't make account appear active. Just because git-annex is being an XMPP
+   client, it doesn't mean that it wants to get chat messages, or make the
+   user appear active when he's not using his chat program.
+
+## protocol
+
+To avoid relying on XMPP extensions, git-annex communicates
+using presence messages. These always mark it as extended away.
+To this, it adds its own tag as [extended content](http://xmpp.org/rfcs/rfc6121.html#presence-extended).
+The xml namespace is "git-annex" (not an URL because I hate wasting bandwidth).
+
+To indicate it's pushed changes to a git repo, a client uses:
+
+	<git-annex xmlns='git-annex' push="uuid" />
+
+The push attribute can be repeated when the push was sent to multiple repos.
+
+### security
+
+Data git-annex sends over XMPP will be visible to the XMPP
+account's buddies, to the XMPP server, and quite likely to other interested
+parties. So it's important to consider the security exposure of using it.
+
+Even if git-annex sends only a single bit notification, this lets attackers
+know when the user is active and changing files. Although the assistant's other
+syncing activities can somewhat mask this.
+
+As soon as git-annex does anything unlike any other client, an attacker can
+see how many clients are connected for a user, and fingerprint the ones
+running git-annex, and determine how many clients are running git-annex.
+
+If git-annex sent the UUID of the remote it pushed to, this would let
+attackers determine how many different remotes are being used,
+and map some of the connections between clients and remotes.
+
+An attacker could replay push notification messages, reusing UUIDs it's
+observed. This would make clients pull repeatedly, perhaps as a DOS.