@@ -14,57 +14,67 @@ If a device takes part in synchronising a group's messages, we say the device is
Each member of a group stores a partial copy of the message graph. Each message in the partial copy of the graph may be **shared** or **deleted**. If a message is shared, the device will synchronise the message to any peers with which it shares the group. If a message is deleted, the device will delete its copy of the message but retain some information about the message's position in the graph.
Each group belongs to a **client**, which is an application that uses BSP to synchronise data. The client is responsible for deciding which peers the group should be shared with, what constitutes a valid message, which messages should be shared, and which messages should be deleted. BSP implements these decisions on behalf of the client.
Each group belongs to a **client**, which is an application component that uses BSP to synchronise data. The client is responsible for deciding which peers the group should be shared with, what constitutes a valid message, which messages should be shared, and which messages should be deleted. BSP implements these decisions on behalf of the client.
### 1.2 Transport Layer Security
BSP requires a **transport layer security protocol** that can deliver data from one device to another on a best-effort basis, meaning that data may be delayed, lost, reordered or duplicated. The transport layer security protocol is responsible for ensuring the confidentiality, integrity, authenticity and forward secrecy of the data it carries.
### 1.3 Cryptographic Primitives
### 1.3 Notation
**Notation:** || denotes concatenation, double quotes denote an ASCII string, and len(x) denotes the length of x in bytes, represented as a 32-bit integer. All integers in BSP are big-endian.
* || denotes concatenation
* Double quotes denote an ASCII string
* len(x) denotes the length of x in bytes
* int\_n(x) denotes x represented as an unsigned, big-endian, n-bit integer
BSP uses two cryptographic primitives:
### 1.4 Cryptographic Primitives
1.**A cryptographic hash function**, H(m)
2.**A random number generator**, R(n), with a output length of n bytes
All hashes are HASH\_LEN bytes. (*Note:* The current version of the protocol uses BLAKE2s as the hash function, giving HASH\_LEN = 32.)
BSP uses a **cryptographic hash function**, H(m).
We use H(m) to define a multi-argument hash function:
R(n) must be either a true random number generator or a cryptographically secure pseudo-random number generator.
All hashes are HASH\_LEN bytes.
(*Note:* The current version of the protocol uses BLAKE2b as the hash function, with an output length of 32 bytes, giving HASH\_LEN = 32.)
## 2 Data Formats
### 2.1 Client Identifiers
Each client has a unique random identifier HASH\_LEN bytes long:
Each client is identified by a namespaced string. The namespace is based on domain names and is intended to prevent accidental collisions between clients created by different developers. For example, all clients developed by the Briar project have identifiers starting with `org.briarproject`.
### 2.2 Client Versioning
BSP uses a major/minor numbering scheme to distinguish between versions of each client.
The client identifier and major version are included in the calculation of group identifiers, so different major versions of a given client use distinct groups, whereas different minor versions use the same groups.
The minor version is used to indicate backward-compatible changes. A client may not send a message that another client with the same identifier and major version but a different minor version would not be able to handle.
- client\_id = R(HASH\_LEN)
The major version is used to indicate backward-incompatible changes. A client may send a message that another client with the same identifier but a different major version would not be able to handle. The use of distinct groups for each major version makes this safe.
The client identifier is generated by the client developer and serves to prevent collisions between groups and messages belonging to different clients.
### 2.3 Groups
### 2.2 Groups
Each group has a unique identifier HASH\_LEN bytes long. The identifier is calculated by hashing the client identifier and major version with a byte string called the **group descriptor**:
Each group has a unique identifier HASH\_LEN bytes long. The identifier is calculated by hashing the client identifier and a byte string called the **groupdescriptor**:
The format version is 1 for the current version of BSP.
The group descriptor is supplied by the client and is not interpreted by BSP. The maximum length of a group descriptor is 2<sup>15</sup> bytes (32 KiB).
The group descriptor is supplied by the client and is not interpreted by BSP. The maximum length of a group descriptor is 16 KiB.
### 2.3 Messages
### 2.4 Messages
A message consists of a byte string called the **message body** and a timestamp indicating the time at which the message was created. The timestamp is a 64-bit integer representing milliseconds since the Unix epoch.
A message consists of a byte string called the **message body** and a timestamp indicating the time at which the message was created, represented in milliseconds since the Unix epoch.
The message body is supplied by the client and is not interpreted by BSP. The maximum length of a message body is 2<sup>15</sup> bytes (32 KiB).
The message body is supplied by the client and is not interpreted by BSP. The maximum length of a message body is 32 KiB.
Each message has a unique identifier HASH\_LEN bytes long. The identifier is calculated by hashing the group identifier, timestamp and message body:
@@ -76,33 +86,41 @@ Peers synchronise data by exchanging **records** via the transport layer securit
- Bits 16-31: Length of the payload in bytes as a 16-bit integer
The current version of the protocol is 1, which has four record types:
The maximum length of the payload is 48 KiB.
**0: ACK** - The payload consists of one or more message identifiers. This record informs the recipient that the sender holds the listed messages.
The current version of the protocol is 0, which has five record types:
**1: MESSAGE** - The payload consists of a message (group identifier, timestamp and message body).
**0: ACK** - The record's payload consists of one or more message identifiers. This record informs the recipient that the sender has seen the listed messages.
**2: OFFER** - The payload consists of one or more message identifiers. This record informs the recipient that the sender holds the listed messages, is sharing them with the recipient, and does not know whether the recipient holds them.
**1: MESSAGE** - The record's payload consists of a message (group identifier, timestamp and message body).
**3: REQUEST** - The payload consists of one or more message identifiers. This record asks the recipient to send the listed messages to the sender.
**2: OFFER** - The record's payload consists of one or more message identifiers. This record informs the recipient that the sender has seen the listed messages, is sharing them with the recipient, and does not know whether the recipient has seen them.
**3: REQUEST** - The record's payload consists of one or more message identifiers. This record asks the recipient to send the listed messages to the sender.
**4: VERSIONS** - The record's payload consists of up to ten 8-bit integers, each identifying a version of BSP supported by the sender. This record will be used for version negotiation by future versions of BSP.
A device should reject any record with an unsupported protocol version and ignore any record with a supported protocol version but an unrecognised record type. This allows new record types to be added without breaking compatibility.
## 4 Synchronisation
### 4.1 Synchronisation State
A device stores the following synchronisation state for each message it is sharing with each of its peers:
A device stores the following synchronisation state for each message it is sharing with a peer:
-**Hold flag** - Set to one if the peer is known to hold the message, otherwise zero
-**Seen flag** - Raised if the peer is known to have seen the message, otherwise lowered
-**Ack flag** - Set to one if the device needs to acknowledge receipt of the message from the peer, otherwise zero
-**Ack flag** - Raised if the peer has offered or sent the message since the device last acknowledged it, otherwise lowered
-**Request flag** - Set to one if the peer has requested the message since the device last offered or sent it, otherwise zero
-**Request flag** - Raised if the peer has requested the message since the device last offered or sent it, otherwise lowered
-**Send count** - The number of times the message has been offered or sent to the peer
-**Send time** - The time at which the message can next be offered or sent to the peer
The device also stores a list of message identifiers that have been offered by the peer and not yet acknowledged or requested by the device. The length of this list should be bounded, and the device should replace the oldest entry in the list if the maximum length is reached. The maximum length of the list is an implementation parameter.
-**Expected arrival time** - The time at which the offer or message is expected to arrive at the peer, or zero if the message has not been offered or sent to the peer
The device may also store a list of message identifiers that have been offered by the peer and not yet requested by the device. This list allows requests to be sent asynchronously. The length of the list may be bounded and the peer may discard offered message identifiers when the list is full.
### 4.2 Synchronisation Modes
...
...
@@ -110,7 +128,7 @@ Each time a device has an opportunity to send records to a peer, it decides whet
Interactive mode uses less bandwidth than batch mode, but needs two round-trips for synchronisation, whereas batch mode needs one.
A device may choose a mode based on prior knowledge or measurements of the underlying transport, such as the round-trip time, or it may use any other method. BSP does not specify how to decide which mode to use - devices may use different methods, and may change their methods at any time. It is not necessary for peers to choose the same mode.
The device may choose a mode based on prior knowledge or measurements of the underlying transport, such as the round-trip time, or it may use any other method. Devices may use different methods from their peers.
##### Interactive Mode
...
...
@@ -118,13 +136,13 @@ In interactive mode, messages are offered before being sent. The device does the
-**Acknowledge** any messages **received** from the peer that the device has not yet acknowledged
-**Acknowledge** any messages **offered** by the peer that the device holds, and has not yet acknowledged
-**Acknowledge** any messages **offered** by the peer that the device has seen and has not yet acknowledged
-**Request** any messages **offered** by the peer that the device does not hold, and has not yet requested
-**Request** any messages **offered** by the peer that the device has not seen and has not yet requested
-**Send** any messages that the device is **sharing** with the peer, that have been **requested** by the peer, and that have reached their send times
-**Send** any messages that the device is **sharing** with the peer, that have been **requested** by the peer, and that are **ready to send** (see below)
-**Offer** any messages that the device is **sharing** with the peer, and does not know whether the peer holds, and that have reached their send times
-**Offer** any messages that the device is **sharing** with the peer, and does not know whether the peer has seen, and that are ready to send
##### Batch Mode
...
...
@@ -132,19 +150,23 @@ In batch mode, messages are sent without being offered. The device does the foll
-**Acknowledge** any messages **sent** by the peer that the device has not yet acknowledged
-**Acknowledge** any messages **offered** by the peer that the device holds, and has not yet acknowledged
-**Acknowledge** any messages **offered** by the peer that the device has seen and has not yet acknowledged
-**Request** any messages **offered** by the peer that the device does not hold, and has not yet requested
-**Request** any messages **offered** by the peer that the device has not seen and has not yet requested
-**Send** any messages that the device is **sharing** with the peer, that have been **requested** by the peer, and that have reached their send times
-**Send** any messages that the device is **sharing** with the peer, that have been **requested** by the peer, and that are ready to send
-**Send** any messages that the device is **sharing** with the peer, and does not know whether the peer holds, and that have reached their send times
-**Send** any messages that the device is **sharing** with the peer, and does not know whether the peer has seen, and that are ready to send
### 4.3 Retransmission
Whenever a device offers or sends a message to a peer, it increases the message's **send count** and **send time**.
Whenever a device offers or sends a message to a peer, it increases the message's **send count** and **send time** and updates the message's **expected arrival time**.
A device may increase the send time based on prior knowledge or measurements of the underlying transport, such as the round-trip time, or it may use any other method. Devices may use different methods from their peers. BSP only requires that the amount by which the send time is increased should increase exponentially with the send count. In other words, retransmission should use some form of exponential backoff.
Similarly, a device may update the expected arrival time based on prior knowledge or measurements of the underlying transport, or it may use any other method. Devices may use different methods from their peers.
A device may increase the send time based on prior knowledge or measurements of the underlying transport, such as the round-trip time, or it may use any other method. BSP does not specify how the send time should be increased, except that the amount by which it is increased should increase exponentially with the send count. Devices may use different methods, and may change their methods at any time. It is not necessary for peers to use the same method.
A message is considered **ready to send** if either its send time has been reached, or the expected arrival time would be reduced if the message was sent now.
