From fd81961d3e5589be056f7fbf1e37bebf11e0f4d0 Mon Sep 17 00:00:00 2001
From: akwizgran <akwizgran@users.sourceforge.net>
Date: Wed, 31 Aug 2016 21:06:31 +0100
Subject: [PATCH] Added message graph section to BSP spec.

---
 protocols/BSP.md | 28 +++++++++++++++++++---------
 protocols/BTP.md | 14 ++++++--------
 2 files changed, 25 insertions(+), 17 deletions(-)

diff --git a/protocols/BSP.md b/protocols/BSP.md
index 6148bf9..2eb8d0f 100644
--- a/protocols/BSP.md
+++ b/protocols/BSP.md
@@ -10,17 +10,17 @@ BSP synchronises data among dynamic sets of **devices**. Each device has a dynam
 
 Data is organised into **groups**. Each group is an independent synchronisation scope containing a **message graph** made up of immutable **messages**.
 
-If a device takes part in synchronising a group's messages, we say the device is a **member** of the group. If two peers synchronise a group's messages with each other, we say they **share** the group with each other. Peers that are members of a group do not necessarily share it with each other. Membership and sharing are dynamic.
+If a device takes part in synchronising a group's messages, we say the device is a **member** of the group. If two peers synchronise a group's messages with each other, we say they **share** the group with each other. Group membership and sharing are dynamic. Peers that are members of a group do not necessarily share it with each other.
 
-Each member of a group keeps a partial copy of the message graph. Each message in the member's copy of the graph may be **shared**, **unshared** 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 unshared, the device will retain its local copy but will not synchronise the message to its peers. If a message is deleted, the device no longer has a copy of the message's content.
+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 application**, which is responsible for deciding which peers the group should be shared with, what constitutes a valid message, and whether each message should be shared, unshared or deleted. BSP implements these policies on behalf of the client.
+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.
 
-A message graph is a directed acyclic graph where each message points to its **dependencies**. BSP provides **causal consistency**, meaning that a message is not delivered to the client until its dependencies have been delivered. If the client shares a message then its dependencies are also shared.
+### 1.2 Transport Layer Security
 
-BSP requires a **transport layer security protocol** that can deliver data from a sender to a recipient 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.
+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.2 Cryptographic Primitives
+### 1.3 Cryptographic Primitives
 
 **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.
 
@@ -48,7 +48,7 @@ Each client has a unique random identifier HASH\_LEN bytes long:
 
 The client identifier is generated by the client developer and serves to prevent collisions between groups and messages belonging to different clients.
 
-### 2.2 Group Identifiers
+### 2.2 Groups
 
 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 **group descriptor**:
 
@@ -62,8 +62,6 @@ A message consists of a byte string called the **message body** and a timestamp
 
 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).
 
-### 2.4 Message Identifiers
-
 Each message has a unique identifier HASH\_LEN bytes long. The identifier is calculated by hashing the group identifier, timestamp and message body:
 
 - message\_id = HASH("MESSAGE\_ID", group\_id, timestamp, message\_body)
@@ -147,3 +145,15 @@ In batch mode, messages are sent without being offered. The device does the foll
 Whenever a device offers or sends a message to a peer, it increases the message's **send count** and **send 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. 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.
+
+## 5 The Message Graph
+
+Each group belongs to a client that 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.
+
+The message graph is a directed graph where each message points to its **dependencies**. The list of dependencies is encoded in the message body in a format determined by the client. Since messages are immutable, dependency relationships are also immutable and the graph is acyclic. The graph may have more than one component.
+
+When a device receives a message for the first time, the client responsible for the corresponding group parses the message body and extracts a list of dependencies. BSP uses the list of dependencies to determine the message's position in the message graph. If the client cannot parse the message, BSP marks it as invalid and deletes it. Any messages that transitively depend on it are also marked as invalid and deleted.
+
+A message is eligible to be **delivered** to the client when all its dependencies have been delivered. This provides **causal consistency**. When a message is delivered, the client validates the message in the context of its dependencies. If the client decides the message is invalid, BSP marks it as invalid and deletes it. Any messages that transitively depend on it are also marked as invalid and deleted.
+
+The client may share any message that has been delivered, in which case the message's transitive dependencies are also shared. The client may delete any message that it no longer needs to store. This does not affect the message's dependencies or dependents.
diff --git a/protocols/BTP.md b/protocols/BTP.md
index 1c203cd..1fe9efa 100644
--- a/protocols/BTP.md
+++ b/protocols/BTP.md
@@ -8,7 +8,7 @@ BTP's main components are a time-based key management protocol and a wire protoc
 
 BTP is designed for use in censorship-resistant delay-tolerant overlays. By providing consistent security properties for a very wide range of transports, BTP simplifies the design and implementation of such overlays.
 
-BTP can operate over any transport that can deliver a stream of bytes from a sender to a recipient on a best-effort basis, meaning that streams may be delayed, lost, reordered or duplicated. The underlying transport is not required to provide any security properties.
+BTP can operate over any transport that can deliver a stream of bytes from one device to another on a best-effort basis, meaning that streams may be delayed, lost, reordered or duplicated. The underlying transport is not required to provide any security properties.
 
 The BTP wire protocol includes optional padding and does not use any timeouts, handshakes or plaintext headers. This makes BTP compatible with traffic analysis prevention techniques such as traffic morphing, with the goal of making it difficult to distinguish BTP from other protocols.
 
@@ -22,7 +22,7 @@ The primary motivation for BTP's design is to provide a building block for censo
 
 BTP is therefore designed to be used across a diverse mixture of transports, both online and offline, with varying properties. The transports are not given access to unencrypted or unauthenticated data; nor are they required to ensure the confidentiality, integrity, authenticity or forward secrecy of the data they carry. BTP is responsible for providing those properties.
 
-BTP is unusual in that it provides forward secrecy without ongoing two-way communication, and also has features that can make it non-trivial for an adversary to detect when BTP is in use.
+BTP is unusual in that it provides forward secrecy without ongoing two-way communication, and also has features that can make it non-trivial for an adversary to detect when BTP is in use. It can be used even on transports with very high latency, such as disks sent through the mail.
 
 ### 1.2 Design Requirements
 
@@ -70,15 +70,13 @@ BTP is intended to be used in systems that resist surveillance and censorship by
 
 ### 1.4 Underlying Transports
 
-BTP can operate over any transport that can deliver a unidirectional or bidirectional sequence of bytes, which we refer to as a **connection**. BTP uses each unidirectional connection to carry an encrypted and authenticated sequence of bytes, which we refer to as a **stream**. BTP treats each bidirectional connection as a pair of complementary unidirectional connections and uses it to carry a stream in each direction.
+BTP can operate over any transport that can deliver a unidirectional or bidirectional sequence of bytes from one device to another on a best-effort basis. We refer to this sequence of bytes as a **connection**. If the connection is unidirectional, BTP uses it to carry an encrypted and authenticated sequence of bytes, which we refer to as a **stream**. If the connection is bidirectional, BTP uses it to carry two separate streams, one in each direction.
 
 Transports must ensure that bytes within a given connection arrive in the correct order. If the bytes within a connection are reordered, none of BTP's security properties are lost, but it will reject the stream or streams carried by the connection.
 
 Transport connections themselves may be reordered. There is no requirement that all connections reach the intended recipient.
 
-BTP can be used even on transports with very high latency, such as disks sent through the mail.
-
-If a transport imposes a maximum connection length, such as the storage capacity of a disk, BTP passes this restriction on to higher protocol layers; it does not fragment a stream across multiple connections. BTP cannot use transport connections with a capacity less than the minimum length of a stream. (*Note:* In the current version of the protocol, the minimum length of a stream is 100 bytes.)
+If a transport imposes a maximum connection length, such as the storage capacity of a disk, BTP passes this restriction on to higher protocol layers; it does not fragment a stream across multiple connections. BTP cannot use transport connections with less capacity than the minimum length of a stream. (*Note:* In the current version of the protocol, the minimum length of a stream is 100 bytes.)
 
 The use of BTP over a datagram-oriented transport such as UDP (which does not have a concept of connections) would require the use of an intermediate connection-oriented protocol such as UDT.
 
@@ -116,7 +114,7 @@ D may be hard-coded. The current version of BTP assumes D = 86,400 (24 hours). T
 
 ##### Maximum latency
 
-Alice and Bob must also agree on a maximum latency for each transport they wish to use. If one endpoint of a connection starts writing to the underlying transport at time T0 and the other endpoint starts reading from the transport at time T1, we call T1 - T0 the latency of the connection. For any given transport we can choose some maximum latency, L , such that the latency of any connection is unlikely to exceed L under normal conditions. For example, we might choose one minute as the maximum latency for TCP, or two weeks as the maximum latency for disks sent through the mail.
+Alice and Bob must agree on a maximum latency for each transport they wish to use. If one endpoint of a connection starts writing to the transport at time T0 and the other endpoint starts reading from the transport at time T1, we call T1 - T0 the latency of the connection. For any given transport we can choose some maximum latency, L , such that the latency of any connection is unlikely to exceed L under normal conditions. For example, we might choose one minute as the maximum latency for TCP, or two weeks as the maximum latency for disks sent through the mail.
 
 If a connection exceeds the maximum latency, none of BTP's security properties are lost but it may reject the stream or streams carried by the connection.
 
@@ -262,7 +260,7 @@ The nonce for the frame body is NONCE\_LEN bytes long, with the following format
 
 The encrypted and authenticated frame header is 4 + AUTH\_LEN bytes long, while the encrypted and authenticated frame body is AUTH\_LEN bytes longer than the data and padding.
 
-## 4 Reordering windows
+## 4 Reordering Windows
 
 BTP uses **reordering windows** to allow endpoints to recognise streams that are received out of order due to reordering and/or loss of connections by the underlying transport. Each endpoint maintains reordering windows for the previous, current and next rotation periods. The windows are used to recognise incoming streams by their tags.
 
-- 
GitLab