@@ -4,6 +4,7 @@ weight = 1
44template = "doc.html"
55aliases = ["/docs/learn/arvo/ames/"]
66+++
7+
78Our networking protocol.
89
910Ames is the name of both our network and the vane that communicates
@@ -11,7 +12,7 @@ over it. When Unix receives a packet over the correct UDP port, it pipes
1112it straight into Ames for handling. Also, all packets sent over the
1213Ames network are sent by the Ames vane. Apps and vanes may use
1314Ames to directly send messages to other ships. In general, apps use
14−[Gall](/docs/userspace/gall/gall) and [Clay](/docs/arvo/clay/clay)
15+[Gall](/docs/arvo/gall/gall) and [Clay](/docs/arvo/clay/clay)
1516to communicate with other ships rather than using Ames
1617directly, but this isn't a requirement. Of course, Gall and Clay use
1718Ames behind the scenes to communicate across the network. Jael is the only other
@@ -25,32 +26,33 @@ protocol itself, including how to route incoming packets to the correct
2526vane or app, is defined in Ames.
2627
2728## Technical Overview
29+
2830This section summarizes the design of Ames. Beyond this section are deeper
2931elaborations on the concepts presented here.
3032
3133Ames extends [Arvo's](/docs/arvo/overview) `%pass`/`%give` `move` semantics across the network.
3234
3335Ames receives packets as Arvo events and emits packets as Arvo
34−effects. The runtime is responsible for transferring the bytes in
36+effects. The runtime is responsible for transferring the bytes in
3537an Ames packet across a physical network to another ship.
3638
3739The runtime tells Ames which physical address a packet came from,
38−represented as an opaque atom. Ames can emit a packet effect to
40+represented as an opaque atom. Ames can emit a packet effect to
3941one of those opaque atoms or to the Urbit address of a galaxy
4042(root node), which the runtime is responsible for translating to a
41−physical address. One runtime implementation sends UDP packets
43+physical address. One runtime implementation sends UDP packets
4244using IPv4 addresses for ships and DNS lookups for galaxies, but
4345other implementations may overlay over other kinds of networks.
4446
45−A local vane can pass Ames a `%plea` request message. Ames
47+A local vane can pass Ames a `%plea` request message. Ames
4648transmits the message over the wire to the peer ship's Ames, which
4749passes the message to the destination vane.
4850
4951Once the peer has processed the `%plea` message, it sends a
5052message-acknowledgment packet over the wire back to the local
51−Ames. This "ack" can either be positive to indicate the request was
53+Ames. This "ack" can either be positive to indicate the request was
5254processed, or negative to indicate the request failed, in which
53−case it's called a "nack". (Don't confuse Ames nacks with TCP
55+case it's called a "nack". (Don't confuse Ames nacks with TCP
5456nacks, which are a different concept).
5557
5658When the local Ames receives either a positive message-ack or a
@@ -60,11 +62,11 @@ requested the original `%plea` message be sent.
6062
6163A local vane can give Ames zero or more `%boon` response messages in
6264response to a `%plea`, on the same duct that Ames used to pass the
63−`%plea` to the vane. Ames transmits a `%boon` over the wire to the
65+`%plea` to the vane. Ames transmits a `%boon` over the wire to the
6466peer's Ames, which gives it to the destination vane on the same
6567duct the vane had used to pass the original `%plea` to Ames.
6668
67−`%boon` messages are acked automatically by the receiver Ames. They
69+`%boon` messages are acked automatically by the receiver Ames. They
6870cannot be nacked, and Ames only uses the ack internally, without
6971notifying the client vane that gave Ames the `%boon`.
7072
@@ -74,15 +76,15 @@ indicating the `%boon` was missed.
7476
7577`%plea` messages can be nacked, in which case the peer will send
7678both a message-nack packet and a naxplanation message, which is
77−sent in a way that does not interfere with normal operation. The
79+sent in a way that does not interfere with normal operation. The
7880naxplanation is sent as a full Ames message, instead of just a
7981packet, because the contained error information can be arbitrarily
80−large. A naxplanation can only give rise to a positive ack --
82+large. A naxplanation can only give rise to a positive ack --
8183never ack an ack, and never nack a naxplanation.
8284
8385Ames guarantees a total ordering of messages within a "flow",
8486identified in other vanes by a duct and over the wire by a `bone`:
85−an opaque number. Each flow has a FIFO (first-in-first-out) queue of `%plea` requests
87+an opaque number. Each flow has a FIFO (first-in-first-out) queue of `%plea` requests
8688from the requesting ship to the responding ship and a FIFO queue
8789of `%boon`'s in the other direction.
8890
@@ -94,23 +96,23 @@ destination vane.
9496
9597Ames encrypts every message using symmetric-key encryption by
9698performing an elliptic curve Diffie-Hellman using our private key
97−and the public key of the peer. For ships in the Jael PKI
99+and the public key of the peer. For ships in the Jael PKI
98100(public-key infrastructure), Ames looks up the peer's public key
99−from Jael. Comets (128-bit ephemeral addresses) are not
101+from Jael. Comets (128-bit ephemeral addresses) are not
100102cryptographic assets and must self-attest over Ames by sending a
101103single self-signed packet containing their public key.
102104
103105When a peer suffers a continuity breach, Ames removes all
104−messaging state related to it. Ames does not guarantee that all
105−messages will be fully delivered to the now-stale peer. From
106+messaging state related to it. Ames does not guarantee that all
107+messages will be fully delivered to the now-stale peer. From
106108Ames's perspective, the newly restarted peer is a new ship.
107109Ames's guarantees are not maintained across a breach.
108110
109111A vane can pass Ames a `%heed` `$task` to request Ames track a peer's
110−responsiveness. If our `%boon`'s to it start backing up locally,
112+responsiveness. If our `%boon`'s to it start backing up locally,
111113Ames will give a `%clog` back to the requesting vane containing the
112−unresponsive peer's urbit address. This interaction does not use
113−ducts as unique keys. Stop tracking a peer by sending Ames a
114+unresponsive peer's urbit address. This interaction does not use
115+ducts as unique keys. Stop tracking a peer by sending Ames a
114116`%jilt` `$task`.
115117
116118Debug output can be adjusted using `%sift` and `%spew` `$task`'s.
@@ -128,46 +130,46 @@ There is a 32-bit header followed by a variable width body.
128130
129131The 32-bit header is given by the following data, presented in order:
130132
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#mug)
139− - 1 bit: is this relayed? (if set, `origin` will be present in the body)
133+- 3 bits: reserved
134+- 1 bit: is this Ames? (i.e. not using a different protocol, such as the
135+ planned remote scry protocol)
136+- 3 bits: Ames protocol version (currently 0)
137+- 2 bits: sender address size
138+- 2 bits: receiver address size
139+- 20 bits: checksum (truncated insecure hash of the body, done with
140+ [`+mug`](/docs/hoon/reference/stdlib/2e#mug)
141+- 1 bit: is this relayed? (if set, `origin` will be present in the body)
140142
141− Every packet sent between ships is encrypted except for self-signed attestation packets from 128-bit comets.
143+Every packet sent between ships is encrypted except for self-signed attestation packets from 128-bit comets.
142144
143145#### Body
144146
145147The body is of variable length and consists of the following parts in this
146148order:
147149
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
156−
157− `origin` is the IP and port of the original sender if the packet was proxied
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)). 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) 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#en).
150+- 4 bits: sender life (mod 16)
151+- 4 bits: receiver life (mod 16)
152+- variable: sender address
153+- variable: receiver address
154+- 48 bits: (optional) 48-bit `origin`
155+- 128 bits: `SIV`
156+- 16 bits: ciphertext size
157+- variable: ciphertext
158+
159+`origin` is the IP and port of the original sender if the packet was proxied
160+through a relay.
161+
162+`SIV` is a "synthetic initialization vector" as defined in AES-256 SIV, the encryption
163+algorithm utilized to encrypt Ames packets (see the page on [Ames
164+cryptography](/docs/arvo/ames/cryptography)). It is formed from the
165+following noun: `~[sender=@p receiver=@p sender-life=@ receiver-life=@]` (see
166+[Life and Rift](/docs/azimuth/life-and-rift) for information on what `life`
167+is). As this data is in Azimuth, it is not explicitly sent over the wire. Thus
168+the mod 16 sender and receiver life in the first 8 bits are only for quick
169+filtering of honest packets sent to or from a stale life.
170+
171+The ciphertext is formed by `+jam`ming a `$shut-packet` and then encrypting
172+using [`+en:sivc:aes:crypto`](/docs/arvo/reference/cryptography#en).
171173
172174### Packeting
173175
@@ -187,9 +189,7 @@ eventually get through, and when the other side gets them it can put them in the
187189correct order. If Ames doesn't get an ack on a packet then it will resend it
188190until it does. The logic for determining how many packets to send or re-send at what time is performed by an Ames-specific variant of TCP's "NewReno" congestion control algorithm.
189191
190−As each packet in a message is received, Ames decrypts it and stores the message fragment. Once it's received every packet for a message, Ames concatenates the fragments back into a single large atom and uses `+cue` to deserialize that back into the original message noun.
191−
192−
192+As each packet in a message is received, Ames decrypts it and stores the message fragment. Once it's received every packet for a message, Ames concatenates the fragments back into a single large atom and uses `+cue` to deserialize that back into the original message noun.
193193
194194### Acks and Nacks
195195
@@ -221,7 +221,6 @@ Thus a message-level ack must be received before the next message on the flow
221221can begin. The full story is more complicated than this; see the section on
222222[flows](#flows).
223223
224−
225224#### Nacks
226225
227226A nack indicates a negative acknowledgement to a `%plea`, meaning that the
@@ -248,9 +247,11 @@ the receiver will never both perform a `%plea` and return a naxplanation.
248247
249248A fragment ack's contents (before encryption) are a pure function of the
250249following noun:
250+
251251```hoon
252252[our-life her-life bone message-num fragment-num]
253253```
254+
254255This means all re-sends of an ack packet will be bitwise identical to each other, unless one of the peers changes its encryption keys.
255256
256257Each datum in this noun is an atom with the aura `@ud` or an aura that nests
@@ -269,11 +270,11 @@ A message (n)ack is a different kind of ack that is obtained by encrypting the
269270```hoon
270271[our-life her-life bone message-num ok=? lag=@dr]
271272```
273+
272274`ok` is a flag that is set to `%.y` for a message ack and `%.n` for a message
273275nack. In the future, `lag` will be used to
274276describe the time it took to process a message, but for now it is always zero.
275277
276−
277278### Flows
278279
279280Flows are asymmetric communication channels along which two ships send and
@@ -300,10 +301,10 @@ We give an example of such a partition. Let flow 12 be a flow between `~bacbel-t
300301`~bacbel-tagfeg` as the `%plea` sender. Then bones 12-15 are associated with the
301302flow, and the types of packets for each bone are:
302303
303− - bone 12, `%plea`s and acks to `~worwel-sipnum`,
304− - bone 13, `%boon`s and (n)acks to `~bacbel-tagfeg`,
305− - bone 14, acks of naxplanations to `~worwel-sipnum`,
306− - bone 15, naxplanations to `~bacbel-tagfeg`.
304+- bone 12, `%plea`s and acks to `~worwel-sipnum`,
305+- bone 13, `%boon`s and (n)acks to `~bacbel-tagfeg`,
306+- bone 14, acks of naxplanations to `~worwel-sipnum`,
307+- bone 15, naxplanations to `~bacbel-tagfeg`.
307308
308309Each bone is handled separately by congestion control, and this is one reason
309310for their segregation. For example, say a two-packet `%plea` is sent on bone 12,
@@ -379,16 +380,17 @@ private key and the public key of `~worwel-sipnum`, obtained via Jael. Then
379380`~bacbel-tagfeb` sends a packet addressed to `~worwel-sipnum` to `~zod`.
380381
381382The packet has the following format:
382− - The standard Ames header described in [header](#header), where the checksum
383− is the `+mug` of the body, and the sender and receiver ship types are `01`,
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 encrypted fragment of the message `%watch /path/to/recipes`.
383+
384+- The standard Ames header described in [header](#header), where the checksum
385+ is the `+mug` of the body, and the sender and receiver ship types are `01`,
386+ denoting that the sender and receiver are planets. The "is this relayed?" bit
387+ is set to 0 since this is the first hop on the packet route.
388+- The body of this packet will be the life of `~bacbel-tagfeg` mod 16, followed
389+ by the life of `~worwel-sipnum` mod 16, followed by `~bacbel-tagfeg`,
390+ followed by the receiver `~worwel-sipnum`, followed by the origin `~`
391+ (denoting that the ship sending the packet is the origin). After this comes
392+ the payload.
393+- The payload of this packet will be the `+jam` of the `content`, which is an encrypted fragment of the message `%watch /path/to/recipes`.
392394
393395`~zod` receives the packet and reads the body. It sees that it is not the
394396intended recipient of the packet, and so gets ready to forward it to
@@ -398,8 +400,7 @@ with the new mug. Since the packet is being relayed, `~zod` flips the "is it
398400relayed?" bit to `%.y`. `~zod` then forwards the packet to `~worwel-sipnum`.
399401
400402In order to decrypt the packet, `~worwel-sipnum` will need to calculate the
401−associated data vector utilized by SIV, which consists of `~[sender=@p
402−receiver=@p sender-life=@ receiver-life=@]`. It then passes that along with the
403+associated data vector utilized by SIV, which consists of `~[sender=@p receiver=@p sender-life=@ receiver-life=@]`. It then passes that along with the
403404SIV and ciphertext to the decryption function, and receives the unencrypted
404405packet as a return.
405406
@@ -463,4 +464,3 @@ hands it off the the Unix network interface to be sent.
463464Now the receiving King is handed a UDP packet by Unix. The King removes the UDP
464465wrapper, `+jam`s the `lane` on which it heard the packet, and delivers the packet
465466to the Ames vane as an atom by copying the bytes it heard on the UDP port.
466−