@@ -35,7 +35,7 @@ your _Azimuth keys_.
35Only [planets](@/docs/glossary/planet.md), [stars](@/docs/glossary/star.md), and
35Only [planets](@/docs/glossary/planet.md), [stars](@/docs/glossary/star.md), and
36[galaxies](@/docs/glossary/galaxy.md) have Azimuth keys.
36[galaxies](@/docs/glossary/galaxy.md) have Azimuth keys.
37[Moons](@/docs/glossary/moon.md) and [comets](@/docs/glossary/comet.md) do not,
37[Moons](@/docs/glossary/moon.md) and [comets](@/docs/glossary/comet.md) do not,
38−as they do not utilize the Ethereum blockchain.
38+as they do not exist on the Ethereum blockchain.
40It is important to note that no Azimuth keys are stored anywhere within your
40It is important to note that no Azimuth keys are stored anywhere within your
41ship's [pier](@/docs/glossary/pier.md) - Ethereum and Urbit ID are entirely
41ship's [pier](@/docs/glossary/pier.md) - Ethereum and Urbit ID are entirely
@@ -47,37 +47,41 @@ the [Azimuth documentation](@/docs/azimuth/azimuth.md).
48#### Networking keys
48#### Networking keys
50−All communications in Urbit over the [Ames](@/docs/glossary/ames.md) networking
50+All communications in Urbit over the [Ames](@/docs/glossary/ames.md) network
51are end-to-end encrypted, and thus your ship stores its own public/private pair
51are end-to-end encrypted, and thus your ship stores its own public/private pair
52of _networking keys_ utilized for encryption and authentication. Networking keys
52of _networking keys_ utilized for encryption and authentication. Networking keys
53−for all ship types are stored within the ship's Jael vane.
53+for all ship types are stored within the ship's [Jael](@/docs/glossary/jael.md)
54−
54+[vane](@/docs/glossary/vane.md).
55−For planets, stars, and galaxies, your private networking key is a
56+For planets, stars, and galaxies, your networking public key is configured on
56−necessary input (the [keyfile](@/docs/glossary/keyfile.md)) for the initial boot
57−sequence of your ship (sometime called its `%dawn`). The associated public key
58−is then uploaded to the Ethereum blockchain using one of your Azimuth private
57+the Ethereum blockchain using one of your Azimuth private keys - either the one
59−keys - either the one associated to the wallet which owns the ship, or the one
58+associated to the wallet which owns the ship, or the one which holds the
60−which holds the management proxy.
59+[management proxy](@/docs/glossary/proxies.md). This is typically accomplished
61−
60+with Bridge. Your networking private key is a necessary input (the
61+[keyfile](@/docs/glossary/keyfile.md)) for the initial boot sequence of your
62+ship (sometime called its `%dawn`), and this is also provided by Bridge.
64+Public keys for moons are not tracked on the blockchain; instead they are
62−For moons, the private networking key is generated by the parent ship and
65+tracked by their parent ship. The networking private key is generated by the
63−injected into the `%dawn` sequence for the moon, and its public key is stored by
66+parent ship and injected into the `%dawn` sequence for the moon, and its public
64−the parent in its Jael vane. Moon networking keys may be changed by the parent
67+key is stored by the parent in its Jael vane. Networking keys for moons may be
65−ship, but not by the moon itself.
68+changed by the parent ship, but not by the moon itself.
67−For comets, their 128-bit `@p` name is actually their public key, and the
70+For comets, their 128-bit `@p` name is actually their networking public key, and
68−"mining" process to generate a comet consists of guessing a private key for
71+the "mining" process to generate a comet consists of guessing a private key for
69−which the associated public key has a galaxy that has already been pre-assigned
72+which the associated public key for which the last two bytes of their `@p`
70−to assist its peer discovery process. Thus, comets cannot change their
73+matches one of the stars on the comet sponsors list downloaded during boot.
71−networking keys - to get a new private networking key, a new comet must be
74+Thus, comets cannot change their networking keys - to get a new private
72−generated. A comet utilizes its private networking key stored in Jael to sign an
75+networking key, a new comet must be generated. For a comet to perform an initial
76+handshake with another ship, it utilizes its networking private key stored in
73−unencrypted attestation packet to verify that it is the owner of the associated
77+Jael to sign an unencrypted attestation packet to verify that it is the owner of
74−public key. Because of this, it is currently impossible for a ship to initiate
78+the associated public key. Because of this, it is currently impossible for a
75−communication with a comet - the comet must always be the initiator. This means
79+ship to initiate communication with a comet - the comet must always be the
76−that ultimately two comets cannot communicate with one another unless they have
80+initiator. This means that ultimately two comets cannot communicate with one
77−somehow verified each others' public keys via some other method. This is merely
81+another unless they have somehow verified each others' public keys via some
78−a technical limitation imposed by the design of the system, not an intentional
82+other method. This is merely a technical limitation imposed by the design of the
79−handicapping of comet abilities. It is expected that this limitation will
83+system, not an intentional handicapping of comet abilities. A workaround to this
80−someday be lifted.
84+limitation is slated to be implemented as of May 2021.
82### System components
86### System components
@@ -99,17 +103,13 @@ are utilized by Ames. All cryptographic primitives are
99[jetted](@/docs/vere/jetting.md) in Vere with standard vetted implementations of
103[jetted](@/docs/vere/jetting.md) in Vere with standard vetted implementations of
100cryptographic libraries.
104cryptographic libraries.
102−[Vere](@/docs/vere/_index.md) is Urbit's Nock runtime system, written in C.
106+[Vere](@/docs/vere/_index.md) is Urbit's Nock runtime system, written in C. All
103−Correct implementation of cryptographic libraries is difficult, and so all
104−cryptographic functions implemented in Hoon are hinted to the interpreter to run
107+cryptographic functions implemented in Hoon are hinted to the interpreter use
105−vetted cryptographic libraries reviewed by experts instead.
108+the [jet system](@/docs/vere/jetting.md) to run standard vetted cryptographic
107−[Azimuth](@/docs/azimuth/_index.md) is Urbit's Ethereum-based public key
108−infrastructure. `azimuth-tracker` obtains networking public keys for planets,
109−stars, and galaxies from this store, which are then stored in Jael and utilized
110−by Ames for end-to-end encrypted communication.
111+[Azimuth](@/docs/azimuth/_index.md) is an Ethereum-based public key
112+infrastructure utilized by Urbit. `azimuth-tracker` obtains networking public
113+keys for planets, stars, and galaxies from this store, which are then stored in
114+Jael and utilized by Ames for end-to-end encrypted communication.