path: root/proposals/0000-wire-protocol.md

Title: **DEP-0000: Wire Protocol**

Short Name: `0000-wire-protocol`

Type: Standard

Status: Undefined (as of 2018-02-04)

Github PR: (add HTTPS link here after PR is opened)

Authors: [Paul Frazee](https://github.com/pfrazee),
[Bryan Newbold](https://github.com/bnewbold)


# Summary
[summary]: #summary

This DEP describes the Dat wire protocol: a transport-agnostic message stream
spoken between nodes in a swarm of hypercore network peers (including Dat
clients). The wire protocol includes mechanisms for framing, stream encryption,
and feed key authentication.


# Motivation
[motivation]: #motivation

The protocol described here is already in use as of 2017 (by hypercore, Dat,
and Beaker Browser users), and was partially described in an earlier
[whitepaper][whitepaper]. This document fills in some additional details.

[whitepaper]: https://TODO


# Stream Connections
[stream-details]: #stream-details

The Dat wire protocol depends on a lower binary transport channel which
provides the following semantics:

- reliable delivery (no dropped messages, or partial messages)
- in-order delivery of messages

Peers wishing to connect need to discover each other using some mechanism or
another (see forthcoming DEPs on some options; this process is modular and
swappable), and both need to have the public key for the primary hypercore they
wish to exchange.

Messages are framed by the Dat protocol itself (see Messages section for
details).


## Channels
[channels]: #channels

Multiple hypercore registers can be synchronized over the same protocol
connection. Messages pertaining to the separate registers (aka, "Feeds",
"channels") are tagged with an id for disambiguation.

Note that at least one feed is necessary for each connection (for handshaking
to succeed), and that the first feed is the one used for discovery and
as an encryption key.

To initiate a new channel (after the primary is established), 

## Handshake Procedure
[handshake]: #handshake

A handshake procedure needs to occur for each feed on a channel; the first part
of the first handshake happens in cleartext and both validates discovery keys
and establishes encyption paramters used for the rest of the connection. The
first (primary) channel has `id=0`.

The first (cleartext) message is a Feed message, and includes two fields: a
nonce and a discovery key.

The **nonce** is generated by each peer as a random 32-byte sequence.

The **discovery key** is generated from the public encryption key for a
hypercore register (in this case the first, or "primary" register) by using the
public key to sign the 9-byte ASCII string "hypercore" (with no trailing NULL
byte) using the BLAKE2b keyed hashing algorithm (provided by most BLAKE2b hash
implementations). The discovery key is 32 bytes long.

The discovery key is used in cleartext instead of the public key to avoid
leaking the public key to the network; read access to hypercore registers
(including Dat archives) is controlled by limiting access to public keys.

When the connection is first opened, the connecting peer sends their Feed
message. The receiving peer checks that the discovery key was what they were
expecting (eg, that they know of a public key matching that discovery key and
are willing to synchronize the register associated with that key). If so, they
reply with their own Feed. If not, they drop the connection.

Once Feed messages are exchanged, both peers have all information they need to
encrypt all further content on the channel, and do so (see below for details).
The second part of the handshake is to exchange Handshake messages, which set
some parameters for the channel. Handshakes also include the self-identified
peer id, which can be used to detect accidental self-connections or redundant
connections to the same peer (eg, over different transports).


## Encryption Scheme
[encryption]: #encryption

After the first Feed messages are exchanged (one message in each direction, in
cleartext), all further bytes exchanged over the channel are encrypted.

Framing metadata (aka, message length and type) is encrypted, but a third party
could likely infer message lengths (and thus potentially message types) by
observing packet sizes and timing; no padding is applied at the protocol layer.

The encryption scheme used is libsodium's stream primative, specifically the
XSalsa20 cipher. The cipher is fed a shared key (the primary hypercore register
public key), a nonce (selected by the sender and exchanged during handshake),
and a block offset (representing all encrypted bytes sent on the connection in
this direction so far).

*TODO: the following paragraph gets in to implementation details... some mention
of the 64 byte chunks is needed, but maybe not this much detail?*

The specific libsodium function used is usually
`crypto_stream_xsalsa20_xor_ic()`. Some interfacing code is necessary to
process messages that don't align with the cipher's 64-byte chunk size; unused
bytes in any particular chunk can be ignored. For example, if 1000 encrypted
bytes had been sent on a connection already, and then a new 50 byte message
needed to be encrypted and sent, then one would offset the message by `1000 %
64 = 40` bytes and XOR the first 24 bytes against block 15, then XOR the
remaining 26 bytes against block 16. The bytes would be shifted back and
recombined before sending, so only 50 bytes would go down the connection; the
same process would be followed by the receiver.


# Message Details
[message-details]: #message-details

TODO: description of framing

Wire format is `<len>(<header><message>)`. `header` is a varint, of form
`channel << 4 | <4-bit-type>`.

Messages are encoded (serialized) using Google's [profobuf][protobuf] encoding.

[protobuf]: https://TODO

<table>
  <tr><th>`type` code <th>Name
  <tr><td> N/A <td>[Keep-Alive][msg-keepalive]
  <tr><td> 0 <td>[Feed][msg-feed]
  <tr><td> 1 <td>[Handshake][msg-handshake]
  <tr><td> 2 <td>[Info][msg-info]
  <tr><td> 3 <td>[Have][msg-have]
  <tr><td> 4 <td>[Unhave][msg-unhave]
  <tr><td> 5 <td>[Want][msg-want]
  <tr><td> 6 <td>[Unwant][msg-unwant]
  <tr><td> 7 <td>[Request][msg-request]
  <tr><td> 8 <td>[Cancel][msg-cancel]
  <tr><td> 9 <td>[Data][msg-data]
  <tr><td>15 <td>[Extension][msg-extension]
</table>

#### Keep-Alive
[msg-keepalive]: #msg-keepalive

A message of body length 0 (giving a total message size of 1 byte for the `len`
varint) is a keep-alive. Depending on transport and application needs, peers
may optionally send keep-alive messages to help detect and prevent channel
loss. Peers must always handle keep-alive messages correctly (aka, ignore
them), regardless of transport.

TODO: what is a good default interval?

#### Feed
[msg-feed]: #msg-feed

    // type=0, should be the first message sent on a channel
    message Feed {
      required bytes discoveryKey = 1;
      optional bytes nonce = 2;
    }

#### Handshake
[msg-handshake]: #msg-handshake

    // type=1, overall connection handshake. should be send just after the feed message on the first channel only
    message Handshake {
        optional bytes id = 1;
        optional bool live = 2; // keep the connection open forever? both ends have to agree
        optional bytes userData = 3;
        repeated string extensions = 4;
    }

TODO: What are semantics of 'live' bit? what if there is disagreement?

#### Info
[msg-info]: #msg-info

    // type=2, message indicating state changes etc.
    // initial state for uploading/downloading is true
    // if both ends are not downloading and not live it is safe to consider the stream ended
    message Info {
        optional bool uploading = 1;
        optional bool downloading = 2;
    }

#### Have
[msg-have]: #msg-have

    // type=3, what do we have?
    message Have {
        required uint64 start = 1;
        optional uint64 length = 2 [default = 1]; // defaults to 1
        optional bytes bitfield = 3;
    }

#### Unhave
[msg-unhave]: #msg-unhave

    // type=4, what did we lose?
    message Unhave {
        required uint64 start = 1;
        optional uint64 length = 2 [default = 1]; // defaults to 1
    }

#### Want
[msg-want]: #msg-want

    // type=5, what do we want? remote should start sending have messages in this range
    message Want {
        required uint64 start = 1;
        optional uint64 length = 2; // defaults to Infinity or feed.length (if not live)
    }

#### Unwant
[msg-unwant]: #msg-unwant

    // type=6, what don't we want anymore?
    message Unwant {
        required uint64 start = 1;
        optional uint64 length = 2; // defaults to Infinity or feed.length (if not live)
    }

#### Request
[msg-request]: #msg-request

    // type=7, ask for data
    message Request {
        required uint64 index = 1;
        optional uint64 bytes = 2;
        optional bool hash = 3;
        optional uint64 nodes = 4;
    }

#### Cancel
[msg-cancel]: #msg-cancel

    // type=8, cancel a request
    message Cancel {
        required uint64 index = 1;
        optional uint64 bytes = 2;
        optional bool hash = 3;
    }

#### Data
[msg-data]: #msg-data

    // type=9, get some data
    message Data {
        message Node {
            required uint64 index = 1;
            required bytes hash = 2;
            required uint64 size = 3;
        }
        required uint64 index = 1;
        optional bytes value = 2;
        repeated Node nodes = 3;
        optional bytes signature = 4;
    }

#### Extension
[msg-extension]: #msg-extension

`type=15` is an extension message that is encoded like:

    <varint user-type><payload>

# Examples

## Simple Download

Alyssa P Hacker and Ben Bitdiddle want to share a book... B connects to A.

- full public key and discovery key for the connection
- example nonces (in full)
- messages in "struct" syntax and raw hex:
    - B: sends Feed
    - A: replies Feed
    - B: Handshake (downloading, not live)
    - A: Handshake (uploading, not live)
    - B: Info: downloading only
    - A: Info: uploading only
    - B: Have: nothing
    - A: Have: everything
    - B: Want: first register entry
    - A: Data: first entry
    - (repeat for all other chunks)
- connection closes

## Multiple Feeds

Describe in detail how to "add" a new channel (feed/register) to an existing
connection, using Feed (and Handshake?) messages.

## Swarm Synchronization

TODO: should this more involved example actually live here? or in hypercore
DEP? It feels pretty message-level, but does involve more hypercore semantics.

This example wouldn't include actual messages, but would describe an N-way (3+)
node swarm, with a single (complete) seeder, two peers that both download from
the seeder and exchange messages, and a fourth peer that downloads from one of
the non-seeder peers only.

- Peer A: seeder, writer. Starts with full history and appends to log
- Peer B: swarm, reader. Starts with full history. Live connection. Connected
  to A, C, D.
- Peer C: swarm, reader. Starts with sparse (old) history. Only wants "latest"
  data. Connected to A and, B.
- Peer D: like Peer C, but only connected to B.

# Rationale and alternatives
[alternatives]: #alternatives

- Why is this design the best in the space of possible designs?
- What other designs have been considered and what is the rationale for not choosing them?
- What is the impact of not doing this?


# Unresolved questions
[unresolved]: #unresolved-questions

What are extension strings?  What can 'userData' bytes be used for?

Encryption might not make sense in some contexts (eg, IPC, or if the transport
layer is already providing encryption). Should this DEP recognize this
explicitly?

- What parts of the design do you expect to resolve through the DEP consensus process before this gets merged?
- What parts of the design do you expect to resolve through implementation and code review, or are left to independent library or application developers?
- What related issues do you consider out of scope for this DEP that could be addressed in the future independently of the solution that comes out of this DEP?


# Changelog
[changelog]: #changelog

A brief statemnt about current status can go here, follow by a list of dates
when the status line of this DEP changed (in most-recent-last order).

- YYYY-MM-DD: First complete draft submitted for review