@@ -11,7 +11,7 @@ over it. When Unix receives a packet over the correct UDP port, it pipes
11it straight into Ames for handling. Also, all packets sent over the
11it straight into Ames for handling. Also, all packets sent over the
12Ames network are sent by the Ames vane. Apps and vanes may use
12Ames network are sent by the Ames vane. Apps and vanes may use
13Ames to directly send messages to other ships. In general, apps use
13Ames to directly send messages to other ships. In general, apps use
14−[Gall](/docs/userspace/gall/gall) and [Clay](/docs/arvo/clay/clay)
14+[Gall](@/docs/userspace/gall/gall.md) and [Clay](@/docs/arvo/clay/clay.md)
15to communicate with other ships rather than using Ames
15to communicate with other ships rather than using Ames
16directly, but this isn't a requirement. Of course, Gall and Clay use
16directly, but this isn't a requirement. Of course, Gall and Clay use
17Ames behind the scenes to communicate across the network. Jael is the only other
17Ames behind the scenes to communicate across the network. Jael is the only other
@@ -28,7 +28,7 @@ vane or app, is defined in Ames.
28This section summarizes the design of Ames. Beyond this section are deeper
28This section summarizes the design of Ames. Beyond this section are deeper
29elaborations on the concepts presented here.
29elaborations on the concepts presented here.
31−Ames extends [Arvo's](/docs/arvo/overview) `%pass`/`%give` `move` semantics across the network.
31+Ames extends [Arvo's](@/docs/arvo/overview.md) `%pass`/`%give` `move` semantics across the network.
33Ames receives packets as Arvo events and emits packets as Arvo
33Ames receives packets as Arvo events and emits packets as Arvo
34effects. The runtime is responsible for transferring the bytes in
34effects. The runtime is responsible for transferring the bytes in
@@ -128,31 +128,46 @@ There is a 32-bit header followed by a variable width body.
129The 32-bit header is given by the following data, presented in order:
129The 32-bit header is given by the following data, presented in order:
131− - 3 bits: Ames `protocol-version`,
131+ - 3 bits: reserved
132+ - 1 bit: is this Ames? (i.e. not using a different protocol, such as the
133+ planned remote scry protocol)
134+ - 3 bits: Ames protocol version (currently 0)
135+ - 2 bits: sender address size
136+ - 2 bits: receiver address size
132− - 20 bits: a checksum as a truncated insecure hash of the body, done with
137+ - 20 bits: checksum (truncated insecure hash of the body, done with
133− [`+mug`](/docs/hoon/reference/stdlib/2e#mug),
138+ [`+mug`](@/docs/hoon/reference/stdlib/2e.md#mug)
134− - 2 bits: the bit width of the sender address encoded as a 2-bit enum,
139+ - 1 bit: is this relayed? (if set, `origin` will be present in the body)
135− - 2 bits: the bit width of the receiver address encoded as a 2-bit enum,
136− - 1 bit: whether the packet is encrypted or not,
139 Every packet sent between ships is encrypted except for self-signed attestation packets from 128-bit comets.
141 Every packet sent between ships is encrypted except for self-signed attestation packets from 128-bit comets.
143−The body is of variable length and consists of three parts in this order:
145+The body is of variable length and consists of the following parts in this
145− - The `@p` of the sending ship,
148+ - 4 bits: sender life (mod 16)
146− - The `@p` of the receiving ship,
149+ - 4 bits: receiver life (mod 16)
147− - The payload, which is the [`+jam`](/docs/hoon/reference/stdlib/2p#jam) (i.e. serialization) of the noun `[origin content]`.
150+ - variable: sender address
151+ - variable: receiver address
152+ - 48 bits: (optional) 48-bit `origin`
154+ - 16 bits: ciphertext size
155+ - variable: ciphertext
149 `origin` is the IP and port of the original sender if the packet was proxied
157 `origin` is the IP and port of the original sender if the packet was proxied
150− through a relay and null otherwise. `content` is a noun that is either an encrypted ack or an
158+ through a relay.
151− encrypted message fragment, unless it is a comet attestation packet in which
159+
152− case it is unencrypted. `content` is always 1kB in size or less.
160+ `SIV` is a "synthetic initialization vector" as defined in AES-256 SIV, the encryption
153−
161+ algorithm utilized to encrypt Ames packets (see the page on [Ames
154− The sender and receiver live outside of the jammed data section to simplify
162+ cryptography](@/docs/arvo/ames/cryptography.md)). It is formed from the
155− packet filtering for the interpreter.
163+ following noun: `~[sender=@p receiver=@p sender-life=@ receiver-life=@]` (see
164+ [Life and Rift](@/docs/azimuth/life-and-rift.md) for information on what `life`
165+ is). As this data is in Azimuth, it is not explicitly sent over the wire. Thus
166+ the mod 16 sender and receiver life in the first 8 bits are only for quick
167+ filtering of honest packets sent to or from a stale life.
169+ The ciphertext is formed by `+jam`ming a `$shut-packet` and then encrypting
170+ using [`+en:sivc:aes:crypto`](@/docs/arvo/reference/cryptography.md#en).
157### Packeting
172### Packeting
@@ -241,7 +256,7 @@ This means all re-sends of an ack packet will be bitwise identical to each other
241Each datum in this noun is an atom with the aura `@ud` or an aura that nests
256Each datum in this noun is an atom with the aura `@ud` or an aura that nests
242under `@ud`.
257under `@ud`.
244−Here, `our-life` refers to the [`life`](/docs/glossary/breach), or revision
259+Here, `our-life` refers to the [`life`](@/docs/glossary/breach.md), or revision
245number, of the acking ship's networking keys, and `her-life` is the `life` of
260number, of the acking ship's networking keys, and `her-life` is the `life` of
246the ack-receiving ship's networking keys. `bone` is an opaque number identifying
261the ack-receiving ship's networking keys. `bone` is an opaque number identifying
247the flow. `message-num` denotes the number of the
262the flow. `message-num` denotes the number of the
@@ -319,10 +334,10 @@ with `%boon`s and create congestion there. So naxplanations have their own bone,
319and so do acks to packets that make up a naxplanation, as well as the
334and so do acks to packets that make up a naxplanation, as well as the
320message-level naxplanation ack.
335message-level naxplanation ack.
322−### Packet relaying
337+### Packet relaying and peer discovery
324−Here we describes how the Ames network relays packets. We ignore all details
339+Here we describes how the Ames network relays packets and does peer discovery.
325−about UDP, which occurs at a lower layer than Ames.
340+We ignore all details about UDP, which occurs at a lower layer than Ames.
327When a ship first contacts another ship, it may only know its `@p`, but an IP
342When a ship first contacts another ship, it may only know its `@p`, but an IP
328address and port are necessary for peer-to-peer communication to occur.
343address and port are necessary for peer-to-peer communication to occur.
@@ -330,23 +345,34 @@ Thus the initial correspondence between two ships, or additional correspondence
330following a change in IP or port of one of the parties, will need to be relayed
345following a change in IP or port of one of the parties, will need to be relayed
331by an intermediary that knows the IP and port of the receiving ship.
346by an intermediary that knows the IP and port of the receiving ship.
333−For now packet relaying is handled entirely by galaxies. Every galaxy is
348+For now, peer discovery is handled entirely by galaxies. Every galaxy is
334responsible for knowing the IP and port of every planet underneath it. In the
349responsible for knowing the IP and port of every planet underneath it. In the
335−future, galaxies will only need to know the star sponsoring a planet, and stars
350+future, galaxies will only need to know the IP and port of the star sponsoring a
336−will be responsible for the final step of the relay.
351+planet, and stars will be responsible for knowing the IP and port of their sponsored planets.
353+Galaxies are also utilized for packet relaying in the case where two ships
354+cannot communicate directly with one another, as is often the case when one or
356+[NAT](https://en.wikipedia.org/wiki/Network_address_translation) or certain
357+firewalls. We remark that packet relaying is a necessary component of peer
358+discovery. Thus stars will also assist with packet relaying in the future.
360+In the case of a moon, its parent ship is responsible for packet relaying and peer
361+discovery, analagous to the role that galaxies currently play for stars and planets.
338The following diagram summarizes the packet creation and forwarding process.
363The following diagram summarizes the packet creation and forwarding process.
340<div style="text-align:center">
365<div style="text-align:center">
341−<img src="https://media.urbit.org/docs/arvo/datagram-long.png">
366+<img src="https://media.urbit.org/docs/arvo/datagram-updated-2021-06-09.png">
344We elaborate on the above diagram.
369We elaborate on the above diagram.
346A typical relay will look something like this: `~bacbel-tagfeb` wishes to
371A typical relay will look something like this: `~bacbel-tagfeb` wishes to
347contact `~worwel-sipnum` but does not know the IP address and port at which
372contact `~worwel-sipnum` but does not know the IP address and port at which
348−`~worwel-sipnum` resides. Both planets live under `~zod`, which knows both of
373+`~worwel-sipnum` resides. Both planets are sponsored by a star sponsored by
374+`~zod`, which knows both of their IP addresses and port numbers by virtue of
349−their IP and port numbers by virtue of being the galaxy that both live under.
375+being the galaxy that both live under.
351To prepare, `~bacbel-tagfeb` forms a Diffie-Hellman symmetric key with their own
377To prepare, `~bacbel-tagfeb` forms a Diffie-Hellman symmetric key with their own
352private key and the public key of `~worwel-sipnum`, obtained via Jael. Then
378private key and the public key of `~worwel-sipnum`, obtained via Jael. Then
@@ -355,23 +381,28 @@ private key and the public key of `~worwel-sipnum`, obtained via Jael. Then
355The packet has the following format:
381The packet has the following format:
356 - The standard Ames header described in [header](#header), where the checksum
382 - The standard Ames header described in [header](#header), where the checksum
357 is the `+mug` of the body, and the sender and receiver ship types are `01`,
383 is the `+mug` of the body, and the sender and receiver ship types are `01`,
358− denoting that the sender and receiver are planets. The remainder of the
384+ denoting that the sender and receiver are planets. The "is this relayed?" bit
359− packet is the body.
385+ is set to 0 since this is the first hop on the packet route.
360− - The body of this packet will be the `@p` of the
386+ - The body of this packet will be the life of `~bacbel-tagfeg` mod 16, followed
387+ by the life of `~worwel-sipnum` mod 16, followed by `~bacbel-tagfeg`,
361−sender `~bacbel-tagfeb`, followed by the `@p` of the receiver `~worwel-sipnum`,
388+ followed by the receiver `~worwel-sipnum`, followed by the origin `~`
389+ (denoting that the ship sending the packet is the origin). After this comes
362−followed by the payload.
390+ the payload.
363− - The payload of this packet will be the `+jam` of `[origin content]`. `origin`
391+ - The payload of this packet will be the `+jam` of the `content`, which is an
364−for this initial packet will be `~`, which implies that the packet is
392+ encrypted fragment of the message `%watch /path/to/recipes`.
365−originating from the sender. `content` is the `+jam` of the message, encrypted
366−using the Diffie-Hellman symmetric key that was previously computed.
368`~zod` receives the packet and reads the body. It sees that it is not the
394`~zod` receives the packet and reads the body. It sees that it is not the
369intended recipient of the packet, and so gets ready to forward it to
395intended recipient of the packet, and so gets ready to forward it to
370−`~worwel-sipnum`. First, it [`+cue`s](/docs/hoon/reference/stdlib/2p#cue)
396+`~worwel-sipnum`. First, it replaces the origin field with the IP and port of
371−(deserializes) the payload and changes the `origin` to the IP and port of
397+`~bacbel-tagfeb`, then computes the `+mug` of the body and replaces the checksum
372−`~bacbel-tagfeb`. Then it `+jam`s `[origin content]` to form a new payload, and
398+with the new mug. Since the packet is being relayed, `~zod` flips the "is it
373−`+mug`s that payload to get a new checksum. It replaces the old payload and
399+relayed?" bit to `%.y`. `~zod` then forwards the packet to `~worwel-sipnum`.
374−checksum with the new, and then sends the packet along to `~worwel-sipnum`.
400+
401+In order to decrypt the packet, `~worwel-sipnum` will need to calculate the
402+associated data vector utilized by SIV, which consists of `~[sender=@p
403+receiver=@p sender-life=@ receiver-life=@]`. It then passes that along with the
404+SIV and ciphertext to the decryption function, and receives the unencrypted
376Once `~worwel-sipnum` processes the packet, it will know the IP and port of
407Once `~worwel-sipnum` processes the packet, it will know the IP and port of
377`~bacbel-tagfeb` since `~zod` included it when it forwarded the packet. Thus
408`~bacbel-tagfeb` since `~zod` included it when it forwarded the packet. Thus
@@ -381,12 +412,24 @@ NAT and/or firewall prevents a direct peer-to-peer connection, in which case
381peer-to-peer connection, communication between the two ships will now be direct
412peer-to-peer connection, communication between the two ships will now be direct
382until one of them changes their IP address, port, or networking keys.
413until one of them changes their IP address, port, or networking keys.
415+In this scenario, of course, the message is so short that a single packet would
416+be sufficient to send the message, so the `+cue` of the payload would contain
417+the complete message `%watch /path/to/recipes`. At this point, `~worwel-sipnum`
418+would ack (or nack) the packet, which would perform double duty as a message
419+ack. Assuming that a direct peer-to-peer connection is possible, the ack would
420+be sent directly to `~bacbel-tagfeb` using the IP and port found in the origin
421+field of the received packet rather than being relayed via `~zod`.
423+But if the message were not short enough to be contained in a single packet,
424+each packet would need to be decrypted and `+cue`d to obtain the message
425+fragments that are then put together and `+cue`d again to obtain the complete
385## The Serf and the King
428## The Serf and the King
387Urbit's functionality is split between the two binaries `urbit-worker` (sometimes
430Urbit's functionality is split between the two binaries `urbit-worker` (sometimes
388called the Serf) and `urbit-king` (sometimes called the King). This division of
431called the Serf) and `urbit-king` (sometimes called the King). This division of
389−labor is currently not well-documented outside of the [Vere documents](/docs/vere/), but we summarize it here.
432+labor is currently not well-documented outside of the [Vere documents](@/docs/vere/_index.md), but we summarize it here.
391In short, the Serf is the Nock runtime and so keeps track of the current state
434In short, the Serf is the Nock runtime and so keeps track of the current state
392of Arvo as a Nock noun and updates the state by `%poke`ing it with nouns, and
435of Arvo as a Nock noun and updates the state by `%poke`ing it with nouns, and
@@ -421,3 +464,4 @@ hands it off the the Unix network interface to be sent.
421Now the receiving King is handed a UDP packet by Unix. The King removes the UDP
464Now the receiving King is handed a UDP packet by Unix. The King removes the UDP
422wrapper, `+jam`s the `lane` on which it heard the packet, and delivers the packet
465wrapper, `+jam`s the `lane` on which it heard the packet, and delivers the packet
423to the Ames vane as an atom by copying the bytes it heard on the UDP port.
466to the Ames vane as an atom by copying the bytes it heard on the UDP port.