@@ -11,7 +11,7 @@ over it. When Unix receives a packet over the correct UDP port, it pipes
1111it straight into Ames for handling. Also, all packets sent over the
1212Ames network are sent by the Ames vane. Apps and vanes may use
1313Ames 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)
1515to communicate with other ships rather than using Ames
1616directly, but this isn't a requirement. Of course, Gall and Clay use
1717Ames behind the scenes to communicate across the network. Jael is the only other
@@ -28,7 +28,7 @@ vane or app, is defined in Ames.
2828This section summarizes the design of Ames. Beyond this section are deeper
2929elaborations on the concepts presented here.
3030
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.
3232
3333Ames receives packets as Arvo events and emits packets as Arvo
3434effects. 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.
128128
129129The 32-bit header is given by the following data, presented in order:
130130
131− - 3 bits: Ames `protocol-version`,
132− - 20 bits: a checksum as a truncated insecure hash of the body, done with
133− [`+mug`](/docs/hoon/reference/stdlib/2e#mug),
134− - 2 bits: the bit width of the sender address encoded as a 2-bit enum,
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,
137− - 4 bits: unused.
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
137+ - 20 bits: checksum (truncated insecure hash of the body, done with
138+ [`+mug`](@/docs/hoon/reference/stdlib/2e.md#mug)
139+ - 1 bit: is this relayed? (if set, `origin` will be present in the body)
138140
139141 Every packet sent between ships is encrypted except for self-signed attestation packets from 128-bit comets.
140142
141143#### Body
142144
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
146+order:
144147
145− - The `@p` of the sending ship,
146− - The `@p` of the receiving ship,
147− - The payload, which is the [`+jam`](/docs/hoon/reference/stdlib/2p#jam) (i.e. serialization) of the noun `[origin content]`.
148+ - 4 bits: sender life (mod 16)
149+ - 4 bits: receiver life (mod 16)
150+ - variable: sender address
151+ - variable: receiver address
152+ - 48 bits: (optional) 48-bit `origin`
153+ - 128 bits: `SIV`
154+ - 16 bits: ciphertext size
155+ - variable: ciphertext
148156
149157 `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
151− encrypted message fragment, unless it is a comet attestation packet in which
152− case it is unencrypted. `content` is always 1kB in size or less.
153−
154− The sender and receiver live outside of the jammed data section to simplify
155− packet filtering for the interpreter.
158+ through a relay.
159+
160+ `SIV` is a "synthetic initialization vector" as defined in AES-256 SIV, the encryption
161+ algorithm utilized to encrypt Ames packets (see the page on [Ames
162+ cryptography](@/docs/arvo/ames/cryptography.md)). It is formed from the
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.
168+
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).
156171
157172### Packeting
158173
@@ -241,7 +256,7 @@ This means all re-sends of an ack packet will be bitwise identical to each other
241256Each datum in this noun is an atom with the aura `@ud` or an aura that nests
242257under `@ud`.
243258
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
245260number, of the acking ship's networking keys, and `her-life` is the `life` of
246261the ack-receiving ship's networking keys. `bone` is an opaque number identifying
247262the 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,
319334and so do acks to packets that make up a naxplanation, as well as the
320335message-level naxplanation ack.
321336
322−### Packet relaying
337+### Packet relaying and peer discovery
323338
324−Here we describes how the Ames network relays packets. We ignore all details
325−about UDP, which occurs at a lower layer than Ames.
339+Here we describes how the Ames network relays packets and does peer discovery.
340+We ignore all details about UDP, which occurs at a lower layer than Ames.
326341
327342When a ship first contacts another ship, it may only know its `@p`, but an IP
328343address 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
330345following a change in IP or port of one of the parties, will need to be relayed
331346by an intermediary that knows the IP and port of the receiving ship.
332347
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
334349responsible 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
336−will be responsible for the final step of the relay.
350+future, galaxies will only need to know the IP and port of the star sponsoring a
351+planet, and stars will be responsible for knowing the IP and port of their sponsored planets.
352+
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
355+both are behind a
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.
359+
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.
337362
338363The following diagram summarizes the packet creation and forwarding process.
339364
340365<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">
342367</div>
343368
344369We elaborate on the above diagram.
345370
346371A typical relay will look something like this: `~bacbel-tagfeb` wishes to
347372contact `~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
349−their IP and port numbers by virtue of being the galaxy that both live under.
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
375+being the galaxy that both live under.
350376
351377To prepare, `~bacbel-tagfeb` forms a Diffie-Hellman symmetric key with their own
352378private 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
355381The packet has the following format:
356382 - The standard Ames header described in [header](#header), where the checksum
357383 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
359− packet is the body.
360− - The body of this packet will be the `@p` of the
361−sender `~bacbel-tagfeb`, followed by the `@p` of the receiver `~worwel-sipnum`,
362−followed by the payload.
363− - The payload of this packet will be the `+jam` of `[origin content]`. `origin`
364−for this initial packet will be `~`, which implies that the packet is
365−originating from the sender. `content` is the `+jam` of the message, encrypted
366−using the Diffie-Hellman symmetric key that was previously computed.
384+ denoting that the sender and receiver are planets. The "is this relayed?" bit
385+ is set to 0 since this is the first hop on the packet route.
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`,
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
390+ the payload.
391+ - The payload of this packet will be the `+jam` of the `content`, which is an
392+ encrypted fragment of the message `%watch /path/to/recipes`.
367393
368394`~zod` receives the packet and reads the body. It sees that it is not the
369395intended 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)
371−(deserializes) the payload and changes the `origin` to the IP and port of
372−`~bacbel-tagfeb`. Then it `+jam`s `[origin content]` to form a new payload, and
373−`+mug`s that payload to get a new checksum. It replaces the old payload and
374−checksum with the new, and then sends the packet along to `~worwel-sipnum`.
396+`~worwel-sipnum`. First, it replaces the origin field with the IP and port of
397+`~bacbel-tagfeb`, then computes the `+mug` of the body and replaces the checksum
398+with the new mug. Since the packet is being relayed, `~zod` flips the "is it
399+relayed?" bit to `%.y`. `~zod` then forwards the packet 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
405+packet as a return.
375406
376407Once `~worwel-sipnum` processes the packet, it will know the IP and port of
377408`~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
381412peer-to-peer connection, communication between the two ships will now be direct
382413until one of them changes their IP address, port, or networking keys.
383414
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`.
422+
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
426+message.
384427
385428## The Serf and the King
386429
387430Urbit's functionality is split between the two binaries `urbit-worker` (sometimes
388431called 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.
390433
391434In short, the Serf is the Nock runtime and so keeps track of the current state
392435of 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.
421464Now the receiving King is handed a UDP packet by Unix. The King removes the UDP
422465wrapper, `+jam`s the `lane` on which it heard the packet, and delivers the packet
423466to the Ames vane as an atom by copying the bytes it heard on the UDP port.
467+