From 5455d87b0aa16be1293c79c6bbc9e8726aea1d42 Mon Sep 17 00:00:00 2001 From: Alexis Sellier Date: Thu, 22 Feb 2024 13:13:51 +0100 Subject: [PATCH] Protocol guide updates and improvements --- _guides/protocol.md | 74 ++++++++--- assets/css/main.css | 8 ++ assets/images/announcement-msg.svg | 36 ++++++ assets/images/cob-dag.svg | 122 +++++++++--------- assets/images/federation-vs-p2p.svg | 88 ++++++------- assets/images/multiplexing.svg | 72 +++++------ assets/images/noisexk-1.svg | 35 ++++++ assets/images/noisexk-2.svg | 77 ++++++++++++ assets/images/p2p-network.svg | 186 ++++++++++++++-------------- assets/images/working-vs-stored.svg | 68 +++++----- scripts/cleanup-svgs.sh | 2 +- 11 files changed, 481 insertions(+), 287 deletions(-) create mode 100644 assets/images/announcement-msg.svg create mode 100644 assets/images/noisexk-1.svg create mode 100644 assets/images/noisexk-2.svg diff --git a/_guides/protocol.md b/_guides/protocol.md index ca2bf67..f41e9d3 100644 --- a/_guides/protocol.md +++ b/_guides/protocol.md @@ -83,8 +83,6 @@ server. - - ### Seeding Repositories Whenever a user clones, initializes, or opts to seed a repository, their node's @@ -199,42 +197,83 @@ are relayed between peers to build routing tables that aid in repository discovery and replication. The core functionality is achieved with three message types, each fulfulling a distinct role: -1. **Node Announcements** are used for broadcasting Node IDs and physical +**Node Announcements** are used for broadcasting Node IDs and physical addresses on which a node is publicly reachable, to facilitate peer discovery. -2. **Inventory Announcements** are used for broadcasting repository inventories + +| Node Announcement +| ----------------- +| **`features`** | `u64` | Advertized node capabilities +| **`timestamp`** | `u64` | Message timestamp (unix time) +| **`alias`** | `u8[]` | Non-unique alias (UTF-8) +| **`addresses`** | `Address[]` | External addresses +| **`nonce`** | `u64` | Nonce used for DoS protection + +**Inventory Announcements** are used for broadcasting repository inventories and constructing the routing table which maps out what repositories are hosted where. -3. **Reference Announcements** are used for broadcasting updates to + +| Inventory Announcement +| ---------------------- +| **`inventory`** | `RepoID[]` | Repository inventory +| **`timestamp`** | `u64` | Message timestamp (unix time) + +**Reference Announcements** are used for broadcasting updates to repositories, relayed only to nodes interested in the relevant repository. +| Refs Announcement +| ----------------- +| **`rid`** | `RepoID` | Repository that was updated +| **`refs`** | `{NodeID, OID}[]` | Updated signed refs (`rad/sigrefs`) +| **`timestamp`** | `u64` | Message timestamp (unix time) + + + To prevent endless propagation, nodes drop any message already encountered. However, for the sake of broadcasting messages to new nodes, gossip messages may be temporarily stored and replayed to nodes joining the network for the first time, or after a long period of being offline. -> **Tip**: Refer to [RIP-1][rip-1] to learn more details about Radicle's -> networking protocol. - Each announcement includes the originating *Node ID* along with a *cryptographic signature* and *timestamp*, allowing network participants to verify the authenticity of messages before relaying them to peers.
- -
The three gossip message types.
+ +
Announcement message structure.
+> **Tip**: Refer to [RIP-1][rip-1] to learn more details about Radicle's +> networking protocol. + ### Transport Encryption & Privacy -Connections between peers in the Radicle network are encrypted using the Noise -protocol. This begins with two peers performing a [Diffie-Hellman][ecdh] key +Connections between peers in the Radicle network are encrypted using a [Noise][noise] +protocol handshake. This begins with two peers performing a [Diffie-Hellman][ecdh] key exchange to agree on a shared session key that is used for the duration of the connection. -
- -
Noise XK handshake example.
+Radicle uses the [XK][noise-xk] handshake pattern, which requires the +connection responder's *static key* to be known in advance by the initiator. +This *pre-sharing* takes place over the gossip network via the +`NodeAnnouncement` message, since the static key is simply the Node ID. + + + +
+ +
+ +Once the static key is known, a connection to the node can be initiated +securely, by generating an ephemral key from the static key, using +Diffie-Hellman. The last step involves the initiating node sending its own +static key over the secure channel. + +
+
After the handshake phase is completed, all data exchanged between peers is @@ -291,11 +330,6 @@ In the bootstrapping process, nodes connect to an initial set of bootrap nodes and once they establish a connection, use the regular peer discovery mechanism to find more peers. -
- -
Bootstrapping process.
-
- [bootstrap]: https://en.wikipedia.org/wiki/Bootstrapping_node ### Federation vs. Peer-to-peer diff --git a/assets/css/main.css b/assets/css/main.css index 2a921e6..8dae1be 100644 --- a/assets/css/main.css +++ b/assets/css/main.css @@ -190,6 +190,14 @@ table td { padding: 0.5rem; } +table th { + font-size: var(--font-size-small); + font-weight: var(--font-weight-regular); + background-color: var(--color-bg-dim-0); + padding: 0.5rem; + text-align: left; +} + table code { font-weight: normal; } diff --git a/assets/images/announcement-msg.svg b/assets/images/announcement-msg.svg new file mode 100644 index 0000000..2ec91df --- /dev/null +++ b/assets/images/announcement-msg.svg @@ -0,0 +1,36 @@ + + + + + + + + + + + + + + Message + + + Announcement + + + + + + + Node ID + + + + + + + Signature + + diff --git a/assets/images/cob-dag.svg b/assets/images/cob-dag.svg index 3defc68..2bb6711 100644 --- a/assets/images/cob-dag.svg +++ b/assets/images/cob-dag.svg @@ -1,137 +1,137 @@ - + - - - + + + Comment - - + + - + Edit Comment - - - + + + - + Label - - - + + + Close - - - + + + - + Comment - - - + + + Comment - - - + + + - + Open - - + + - - - + + + - - + + - - - + + + - + - - + + - - + + - - - + + + - - + + - - - + + + - - + + - - - + + + - - + + - - - + + + - + - - + + diff --git a/assets/images/federation-vs-p2p.svg b/assets/images/federation-vs-p2p.svg index 2b956ea..cdce8e2 100644 --- a/assets/images/federation-vs-p2p.svg +++ b/assets/images/federation-vs-p2p.svg @@ -6,196 +6,196 @@ - - + + Instance - - + + User - - + + User - - + + User - - + + User - + - + - + - + - - + + Instance - + - - + + Instance - + - + - - + + User - + - - + + Node - - + + Node - - + + Node - - + + Node - - + + Node - - + + Node - + - + - + - + - + - + - + - + diff --git a/assets/images/multiplexing.svg b/assets/images/multiplexing.svg index eda5a8a..cfec3d6 100644 --- a/assets/images/multiplexing.svg +++ b/assets/images/multiplexing.svg @@ -1,60 +1,62 @@ - - + + + + - - + + - - - + + + - - - + + + - - + + - - - + + + - - - + + + - - + + - - - + + + - - - + + + - - - + + + - + Calyx - - + + Paxel diff --git a/assets/images/noisexk-1.svg b/assets/images/noisexk-1.svg new file mode 100644 index 0000000..8a4f609 --- /dev/null +++ b/assets/images/noisexk-1.svg @@ -0,0 +1,35 @@ + + + + + + + + + + Paxel + + + + + + + + + + + + + Responder gossips static key + + + s + + + + + + diff --git a/assets/images/noisexk-2.svg b/assets/images/noisexk-2.svg new file mode 100644 index 0000000..7d2e02f --- /dev/null +++ b/assets/images/noisexk-2.svg @@ -0,0 +1,77 @@ + + + + + + + + + + + + + + + + + + + + Calyx + + + e, es + + + Initiator sends ephemeral key + + + + + + + Paxel + + + + + + + + + + + + + Responder sends ephemeral key + + + e, ee + + + + + + + + + + + + + + + + + Calyx + + + Initiator sends static key + + + s, se + + diff --git a/assets/images/p2p-network.svg b/assets/images/p2p-network.svg index 3be5dac..66c101c 100644 --- a/assets/images/p2p-network.svg +++ b/assets/images/p2p-network.svg @@ -1,194 +1,194 @@ - + - - - + + + - + Node - - - + + + - + Node - - - + + + - + Node - - - + + + - + Node - - - + + + - + Node - - - + + + - + Node - - + + - - - + + + - - + + - - fetch + + fetch - - + + - - - + + + - - + + - - fetch + + fetch - - + + - - + + - + gossip - - + + - - + + - - - + + + - - + + - - fetch + + fetch - - + + - - - + + + - - + + - + gossip - - + + - - - + + + - - + + - + gossip - - + + - - + + - - + + - - + + - - + + - + Gossip - - + + - - - + + + - - Git fetch + + Git fetch diff --git a/assets/images/working-vs-stored.svg b/assets/images/working-vs-stored.svg index b6d5c8a..73736d0 100644 --- a/assets/images/working-vs-stored.svg +++ b/assets/images/working-vs-stored.svg @@ -6,85 +6,87 @@ - + - - + + - + Repository + - - - + + + - + Repository + - Local Storage + Local Storage - - - + + + - + - Working - Copy + Working + Copy - + - Working - Copy + Working + Copy - + - - + + - - push + + push - + - - + + - - pull + + pull - + Node - - rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5 + + Stored Copy - - rad:z2ATVRDqFu2Yq2MG5ZZCWecwSDYqj + + Stored Copy diff --git a/scripts/cleanup-svgs.sh b/scripts/cleanup-svgs.sh index 94f715b..8705399 100755 --- a/scripts/cleanup-svgs.sh +++ b/scripts/cleanup-svgs.sh @@ -24,7 +24,7 @@ process() { # Remove all instances of `font-family="..."` and `font-size="..."` sed -i -e 's/font-family="[^"]*"//g' -e 's/font-size="16px"//g' "$FILE" # Remove comments. - sed -i -e 's/\n//' "$FILE" + sed -i -e '//d' "$FILE" # Replace the contents of