@@ -5,8 +5,8 @@ template = "doc.html"
55+++
66
77Cryptography is central to the operation of Urbit. This section gives an
8−overview of where cryptographic methods are utilized in Arvo, what they are, and
9−how they are implemented.
8+overview of where cryptographic methods are utilized in Arvo, Azimuth, and Vere,
9+what they are, and how they are implemented.
1010
1111This document does not describe any algorithmic details of cryptographic
1212functions, only how they are utilized. This document also does not yet cover
@@ -16,35 +16,99 @@ functions in the standard library.
1616
1717## Summary
1818
19−There are five parts of the system involved with cryptography on Urbit. We
20−summarize each component here briefly, and then continue with a more detailed
21−exposition below.
19+There are two categories of keys and five parts of the system involved with
20+cryptography on Urbit. We summarize each component here briefly, and then
21+continue with a more detailed exposition below.
22+
23+### Types of keys
24+
25+The two categories of keys are your Azimuth/Ethereum keys and your networking
26+keys. In both cases, these are public/private key pairs utilized for public key
27+cryptography.
28+
29+#### Azimuth keys
30+
31+Your Urbit ID exists as an ERC-721 non-fungible token on the Ethereum
32+blockchain, and as such is contained in a wallet whose private key you possess.
33+If you are are utilizing a [master
34+ticket](@/docs/azimuth/azimuth.md#master-ticket), this private key is derived
35+from a seed, which is what you use to login to
36+[Bridge](@/docs/glossary/bridge.md). Otherwise, you have generated the key by
37+some other process, of which there are too many to list here. Besides the
38+private key which unlocks your ownership wallet address, you may have a few
39+other private keys which unlock a wallet that corresponds to your ship's
40+[proxies](@/docs/glossary/proxies.md). We refer collectively to these keys as
41+your _Azimuth keys_.
42+
43+Only [planets](@/docs/glossary/planet.md), [stars](@/docs/glossary/star.md), and
44+[galaxies](@/docs/glossary/galaxy.md) have Azimuth keys.
45+[Moons](@/docs/glossary/moon.md) and [comets](@/docs/glossary/comet.md) do not,
46+as they do not utilize the Ethereum blockchain.
47+
48+It is important to note that no Azimuth keys are stored anywhere within your
49+ship's [pier](@/docs/glossary/pier.md) - Ethereum and Urbit ID are entirely
50+separate entities from Urbit itself, and so you lose access to your Azimuth
51+private keys there is no way to retrieve them somehow from your ship.
52+
53+For more information on the usage of these keys and the associated proxies, see
54+the [Azimuth documentation](@/docs/azimuth/azimuth.md).
55+
56+#### Networking keys
57+
58+All communications in Urbit over the [Ames](@/docs/glossary/ames.md) are
59+end-to-end encrypted, and thus your ship stores a public/private pair of
60+_networking keys_ utilized to manage that encryption. Networking keys for all
61+ship types are stored within the ship's Jael vane (see the following section).
62+
63+For planets, stars, and galaxies, your private networking key is a
64+necessary input (the [keyfile](@/docs/glossary/keyfile.md)) for the initial boot
65+sequence of your ship (sometime called its `%dawn`). The associated public key
66+is then uploaded to the Ethereum blockchain using one of your Azimuth private
67+keys - either the one associated to the wallet which owns the ship, or the one
68+which holds the management proxy.
69+
70+For moons, the private networking key is generated by the parent ship and
71+injected into the `%dawn` sequence for the moon, and its public key is stored by
72+the parent in its Jael vane. Moon networking keys may be changed by the parent
73+ship, but not by the moon itself.
74+
75+For comets, their 128-bit name is actually their public key, and the "mining"
76+process to generate a comet consists of guessing a private key for which the
77+associated public key has a galaxy that has already been pre-assigned to assist
78+its peer discovery process. Thus, comets cannot change their networking keys -
79+to get a new private networking key, a new comet must be generated.
80+
81+### System components
2282
2383[Ames](@/docs/arvo/ames/ames.md) is Arvo's networking vane. All packets sent by
24−Ames are encrypted utilizing a cryptosuite found in `zuse`. Ames is responsible
25−for encryption and decryption of all packets. By default, this utilizes AES
26−symmetric key encryption, whose key is got by elliptic curve Diffie-Hellman key exchange.
84+Ames are encrypted utilizing a cryptosuite found in `zuse`. The only exception
85+to this are comet self-attestation packets utilized to transmit their public
86+key. Ames is responsible for encryption and decryption of all packets. By
87+default, this utilizes AES symmetric key encryption, whose shared private key is
88+got by elliptic curve Diffie-Hellman key exchange.
2789
2890`zuse` is the Hoon standard library. It contains cryptographic primitives which
29−may be utilized by an Ames `+crypto-core`. All cryptographic primitives are
30−[jetted](@/docs/vere/jetting.md) in Vere with standard implementations of cryptographic
31−libraries.
91+are utilized by Ames. All cryptographic primitives are
92+[jetted](@/docs/vere/jetting.md) in Vere with standard vetted implementations of
93+cryptographic libraries.
3294
3395[Vere](@/docs/vere/_index.md) is Urbit's Nock runtime system, written in C.
3496Correct implementation of cryptographic libraries is difficult, and so all
35−cryptographic primitives implemented in Hoon actually hint to the interpreter to
36−run vetted cryptographic libraries reviewed by experts.
97+cryptographic primitives implemented in Hoon actually hinted to the interpreter
98+to run vetted cryptographic libraries reviewed by experts instead.
3799
38−[Jael](@/docs/arvo/jael/jael-api.md) is utilized for the safe storage and
39−retrieval of private and public keys utilized by Ames and Azimuth. The Jael vane
40−of a planet is responsible for distributing the public keys of its moons
100+[Jael](@/docs/arvo/jael/jael-api.md) is primarily utilized for the safe storage
101+of private keys and retrieval of public keys utilized by Ames. The Jael vane of
102+a planet is responsible for distributing the public keys of its moons
41103(ultimately via Ames), while the Jael vane of a comet is responsible for
42104distributing its own public key (also ultimately via Ames).
43105
44106[Azimuth](@/docs/azimuth/_index.md) is Urbit's Ethereum-based public key
45−infrastructure. `azimuth-tracker` obtains public keys for planets, stars, and
46−galaxies from this store, which are then stored in Jael and utilized by Ames for
47−end-to-end encrypted communication.
107+infrastructure. `azimuth-tracker` obtains networking public keys for planets,
108+stars, and galaxies from this store, which are then stored in Jael and utilized
109+by Ames for end-to-end encrypted communication. It is important to note that the
110+private keys which generate the wallet that holds ownership of your Urbit ID and
111+its proxies are not stored anywhere on your ship.
48112
49113## Ames
50114