271a919d14
For backwards compatability, "" is treated as "0" sequence number. --debug will show xmpp sequence numbers now, but they are not otherwise used.
131 lines
5.4 KiB
Markdown
131 lines
5.4 KiB
Markdown
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
|
|
|
|
* Prevent idle disconnection. Probably means sending or receiving pings,
|
|
but would prefer to avoid eg pinging every 60 seconds as some clients do.
|
|
* Do git-annex clients sharing an account with regular clients cause confusing
|
|
things to happen?
|
|
See <http://git-annex.branchable.com/design/assistant/blog/day_114__xmpp/#comment-aaba579f92cb452caf26ac53071a6788>
|
|
* Support use of a single XMPP account with several separate and
|
|
independant git-annex repos. This probably works for the simple
|
|
push notification use of XMPP, since unknown UUIDs will just be ignored.
|
|
But XMPP pairing and the pushes over XMPP assume that anyone you're
|
|
paired with is intending to sync to your repository.
|
|
|
|
## 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, and chat messages (with empty body tags,
|
|
so clients don't display them).
|
|
|
|
git-annex sets a negative presence priority, to avoid any regular messages
|
|
getting eaten by its clients. It also sets itself extended away.
|
|
Note that this means that chat messages always have to be directed at
|
|
specific git-annex clients.
|
|
|
|
To the presence and chat messages, 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 with a given UUID, a message
|
|
that is sent to all buddies and other clients using the account (no
|
|
explicit pairing needed), it uses a broadcast presence message containing:
|
|
|
|
<git-annex xmlns='git-annex' push="uuid[,uuid...]" />
|
|
|
|
Multiple UUIDs can be listed when multiple clients were pushed. If the
|
|
git repo does not have a git-annex UUID, an empty string is used.
|
|
|
|
To query if other git-annex clients are around, a presence message is used,
|
|
containing:
|
|
|
|
<git-annex xmlns='git-annex' query="" />
|
|
|
|
For pairing, a chat message is sent to every known git-annex client,
|
|
containing:
|
|
|
|
<git-annex xmlns='git-annex' pairing="PairReq|PairAck|PairDone uuid" />
|
|
|
|
### git push over XMPP
|
|
|
|
To indicate that we could push over XMPP, a chat message is sent,
|
|
to each known client of each XMPP remote.
|
|
|
|
<git-annex xmlns='git-annex' canpush="" />
|
|
|
|
To request that a remote push to us, a chat message can be sent.
|
|
|
|
<git-annex xmlns='git-annex' pushrequest="" />
|
|
|
|
When replying to an canpush message, this is directed at the specific
|
|
client that indicated it could push. To solicit pushes from all clients,
|
|
the message has to be sent directed individually to each client.
|
|
|
|
When a peer is ready to send a git push, it sends:
|
|
|
|
<git-annex xmlns='git-annex' startingpush="" />
|
|
|
|
The receiver runs `git receive-pack`, and sends back its output in
|
|
one or more chat messages, directed to the client that is pushing:
|
|
|
|
<git-annex xmlns='git-annex' rp="N">
|
|
007b27ca394d26a05d9b6beefa1b07da456caa2157d7 refs/heads/git-annex report-status delete-refs side-band-64k quiet ofs-delta
|
|
</git-annex>
|
|
|
|
The sender replies with the data from `git push`, in
|
|
one or more chat messages, directed to the receiver:
|
|
|
|
<git-annex xmlns='git-annex' sp="N">
|
|
data
|
|
</git-annex>
|
|
|
|
The value of rp and sp used to be empty, but now it's a sequence number.
|
|
This indicates the sequence of this packet, counting from 1. The receiver
|
|
and sender each have their own sequence numbers. These sequence numbers
|
|
are not really used yet, but are available for debugging.
|
|
|
|
When `git receive-pack` exits, the receiver indicates its exit
|
|
status with a chat message, directed at the sender:
|
|
|
|
<git-annex xmlns='git-annex' rpdone="0" />
|
|
|
|
### 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.
|