open.source/magic-wormhole
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

protocol docs fixups

Browse Source
This commit is contained in:
Brian Warner 2017-04-06 13:52:26 -07:00
parent af3bb0095d
commit ddc6319bf6
2 changed files with 37 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/client-protocol.md
View File

@ -31,9 +31,10 @@ similar negotiation.
At this stage, the client knows the supposed shared key, but has not yet seen At this stage, the client knows the supposed shared key, but has not yet seen
evidence that the peer knows it too. When the first peer message arrives evidence that the peer knows it too. When the first peer message arrives
(i.e. the first message with a `.side` that does not equal our own), it will (i.e. the first message with a `.side` that does not equal our own), it will
be decrypted: if this decryption succeeds, then we're confident that be decrypted: we use authenticated encryption (`nacl.SecretBox`), so if this
*somebody* used the same wormhole code as us. This event pushes the client decryption succeeds, then we're confident that *somebody* used the same
mood from "lonely" to "happy". wormhole code as us. This event pushes the client mood from "lonely" to
"happy".
This might be triggered by the peer's `version` message, but if we had to This might be triggered by the peer's `version` message, but if we had to
re-establish the Rendezvous Server connection, we might get peer messages out re-establish the Rendezvous Server connection, we might get peer messages out
@ -46,14 +47,15 @@ strictly in-order: if we see phases 3 then 2 then 1, all three will be
delivered in sequence after phase 1 is received. delivered in sequence after phase 1 is received.
If any message cannot be successfully decrypted, the mood is set to "scary", If any message cannot be successfully decrypted, the mood is set to "scary",
and the wormhole is closed. All pending Deferreds will be errbacked with some and the wormhole is closed. All pending Deferreds will be errbacked with a
kind of WormholeError, the nameplate/mailbox will be released, and the `WrongPasswordError` (a subclass of `WormholeError`), the nameplate/mailbox
WebSocket connection will be dropped. If the application calls `close()`, the will be released, and the WebSocket connection will be dropped. If the
resulting Deferred will not fire until deallocation has finished and the application calls `close()`, the resulting Deferred will not fire until
WebSocket is closed, and then it will fire with an errback. deallocation has finished and the WebSocket is closed, and then it will fire
with an errback.
Both `version` and all numeric (app-specific) phases are encrypted. The Both `version` and all numeric (app-specific) phases are encrypted. The
message body will be the hex-encoded output of a NACL SecretBox, keyed by a message body will be the hex-encoded output of a NaCl `SecretBox`, keyed by a
phase+side -specific key (computed with HKDF-SHA256, using the shared PAKE phase+side -specific key (computed with HKDF-SHA256, using the shared PAKE
key as the secret input, and `wormhole:phase:%s%s % (SHA256(side), key as the secret input, and `wormhole:phase:%s%s % (SHA256(side),
SHA256(phase))` as the CTXinfo), with a random nonce. SHA256(phase))` as the CTXinfo), with a random nonce.

50
docs/server-protocol.md
View File

@ -50,23 +50,23 @@ the server and both clients, to identify protocol slowdowns and guide
optimization efforts. To support this, the client/server messages include optimization efforts. To support this, the client/server messages include
additional keys. Client->Server messages include a random `id` key, which is additional keys. Client->Server messages include a random `id` key, which is
copied into the `ack` that is immediately sent back to the client for all copied into the `ack` that is immediately sent back to the client for all
commands (and is ignored except for the timing tool). Some client->server commands (logged for the timing tool but otherwise ignored). Some
messages (`list`, `allocate`, `claim`, `release`, `close`, `ping`) provoke a client->server messages (`list`, `allocate`, `claim`, `release`, `close`,
direct response by the server: for these, `id` is copied into the response. `ping`) provoke a direct response by the server: for these, `id` is copied
This helps the tool correlate the command and response. All server->client into the response. This helps the tool correlate the command and response.
messages have a `server_tx` timestamp (seconds since epoch, as a float), All server->client messages have a `server_tx` timestamp (seconds since
which records when the message left the server. Direct responses include a epoch, as a float), which records when the message left the server. Direct
`server_rx` timestamp, to record when the client's command was received. The responses include a `server_rx` timestamp, to record when the client's
tool combines these with local timestamps (recorded by the client and not command was received. The tool combines these with local timestamps (recorded
shared with the server) to build a full picture of network delays and by the client and not shared with the server) to build a full picture of
round-trip times. network delays and round-trip times.
All messages are serialized as JSON, encoded to UTF-8, and the resulting All messages are serialized as JSON, encoded to UTF-8, and the resulting
bytes sent as a single "binary-mode" WebSocket payload. bytes sent as a single "binary-mode" WebSocket payload.
Servers can signal `error` for any message type it does not recognize. Servers can signal `error` for any message type it does not recognize.
Clients and Servers must ignore unrecognized keys in otherwise-recognized Clients and Servers must ignore unrecognized keys in otherwise-recognized
messages. messages. Clients must ignore unrecognized message types from the Server.
## Connection-Specific (Client-to-Server) Messages ## Connection-Specific (Client-to-Server) Messages
@ -74,8 +74,8 @@ The first thing each client sends to the server, immediately after the
WebSocket connection is established, is a `bind` message. This specifies the WebSocket connection is established, is a `bind` message. This specifies the
AppID and side (in keys `appid` and `side`, respectively) that all subsequent AppID and side (in keys `appid` and `side`, respectively) that all subsequent
messages will be scoped to. While technically each message could be messages will be scoped to. While technically each message could be
independent, I thought it would be less confusing to use exactly one independent (with its own `appid` and `side`), I thought it would be less
WebSocket per logical wormhole connection. confusing to use exactly one WebSocket per logical wormhole connection.
The first thing the server sends to each client is the `welcome` message. The first thing the server sends to each client is the `welcome` message.
This is intended to deliver important status information to the client that This is intended to deliver important status information to the client that
@ -123,7 +123,7 @@ all nameplates, even ones which they've allocated themselves.
Nameplates (on the server) must live until the second client has learned Nameplates (on the server) must live until the second client has learned
about the associated mailbox, after which point they can be reused by other about the associated mailbox, after which point they can be reused by other
clients. So if two clients connect quickly, but then maintain a long-lived clients. So if two clients connect quickly, but then maintain a long-lived
wormhole connection, the do not need to consume the limited spare of short wormhole connection, the do not need to consume the limited space of short
nameplates for that whole time. nameplates for that whole time.
The `allocate` command allocates a nameplate (the server returns one that is The `allocate` command allocates a nameplate (the server returns one that is
@ -133,7 +133,9 @@ with all allocated nameplates for the bound AppID: this helps the code-input
tab-completion feature know which prefixes to offer. The `nameplates` tab-completion feature know which prefixes to offer. The `nameplates`
response returns a list of dictionaries, one per claimed nameplate, with at response returns a list of dictionaries, one per claimed nameplate, with at
least an `id` key in each one (with the nameplate string). Future versions least an `id` key in each one (with the nameplate string). Future versions
may record additional attributes in the nameplate records. may record additional attributes in the nameplate records, specifically a
wordlist identifier and a code length (again to help with code-completion on
the receiver).
## Mailboxes ## Mailboxes
@ -162,17 +164,17 @@ interaction. The server records the mood in its "usage" record, so the server
operator can get a sense of how many connections are succeeding and failing. operator can get a sense of how many connections are succeeding and failing.
The moods currently recognized by the Rendezvous Server are: The moods currently recognized by the Rendezvous Server are:
* happy (default): the PAKE key-establishment worked, and the client saw a * `happy` (default): the PAKE key-establishment worked, and the client saw at
valid encrypted message from its peer least one valid encrypted message from its peer
* lonely: the client gave up without hearing anything from its peer * `lonely`: the client gave up without hearing anything from its peer
* scary: the client saw an invalid encrypted message from its peer, * `scary`: the client saw an invalid encrypted message from its peer,
indicating that either the wormhole code was typed in wrong, or an attacker indicating that either the wormhole code was typed in wrong, or an attacker
tried (and failed) to guess the code tried (and failed) to guess the code
* errory: the client encountered some other error: protocol problem or * `errory`: the client encountered some other error: protocol problem or
internal error internal error
The server will also record "pruney" if it deleted the mailbox due to The server will also record `pruney` if it deleted the mailbox due to
inactivity, or "crowded" if more than two sides tried to access the mailbox. inactivity, or `crowded` if more than two sides tried to access the mailbox.
When clients use the `add` command to add a client-to-client message, they When clients use the `add` command to add a client-to-client message, they
will put the body (a bytestring) into the command as a hex-encoded string in will put the body (a bytestring) into the command as a hex-encoded string in
@ -223,7 +225,7 @@ any), and which ones provoke direct responses:
The server stores all messages in a database, so it should not lose any The server stores all messages in a database, so it should not lose any
information when it is restarted. The server will not send a direct information when it is restarted. The server will not send a direct
response until any side-effects (such as the message being added to the response until any side-effects (such as the message being added to the
mailbox) being safely committed to the database. mailbox) have been safely committed to the database.
The client library knows how to resume the protocol after a reconnection The client library knows how to resume the protocol after a reconnection
event, assuming the client process itself continues to run. event, assuming the client process itself continues to run.
@ -232,4 +234,4 @@ Clients which terminate entirely between messages (e.g. a secure chat
application, which requires multiple wormhole messages to exchange application, which requires multiple wormhole messages to exchange
address-book entries, and which must function even if the two apps are never address-book entries, and which must function even if the two apps are never
both running at the same time) can use "Journal Mode" to ensure forward both running at the same time) can use "Journal Mode" to ensure forward
progress is made: see "api.md" (Journal Mode) for details. progress is made: see "journal.md" for details.