@@ -0,0 +1,116 @@
1++++
2+title = "Cryptography"
3+weight = 50
4+template = "doc.html"
5++++
6+
7+Cryptography is central to the operation of Urbit. Here we give an overview of
8+how it is utilized.
9+
10+There are two categories of keys and five components of the system involved with
11+cryptography on Urbit. We first summarize the two categories of keys and how
12+they are utilized by each ship type, then cover how different parts of Urbit are
13+involved in cryptography.
14+
15+### Types of keys
16+
17+The two categories of keys are your Azimuth/Ethereum keys and your networking
18+keys. In both cases, these are public/private key pairs utilized for public key
19+cryptography.
20+
21+#### Azimuth keys
22+
23+Your Urbit ID exists as an ERC-721 non-fungible token on the Ethereum
24+blockchain, and as such is contained in a wallet whose private key you possess.
25+If you are are utilizing a [master
26+ticket](@/docs/azimuth/azimuth.md#master-ticket), this private key is derived
27+from a seed, which is what you use to login to
28+[Bridge](@/docs/glossary/bridge.md). Otherwise, you have generated the key by
29+some other process, of which there are too many to list here. Besides the
30+private key which unlocks your ownership wallet address, you may have a few
31+other private keys which unlock a wallet that corresponds to your ship's
32+[proxies](@/docs/glossary/proxies.md). We refer collectively to these keys as
33+your _Azimuth keys_.
34+
35+Only [planets](@/docs/glossary/planet.md), [stars](@/docs/glossary/star.md), and
36+[galaxies](@/docs/glossary/galaxy.md) have Azimuth keys.
37+[Moons](@/docs/glossary/moon.md) and [comets](@/docs/glossary/comet.md) do not,
38+as they do not exist on the Ethereum blockchain.
39+
40+It is important to note that no Azimuth keys are stored anywhere within your
41+ship's [pier](@/docs/glossary/pier.md) - Ethereum and Urbit ID are entirely
42+separate entities from Urbit itself, and so you lose access to your Azimuth
43+private keys there is no way to retrieve them somehow from your ship.
44+
45+For more information on the usage of these keys and the associated proxies, see
46+the [Azimuth documentation](@/docs/azimuth/azimuth.md).
47+
48+#### Networking keys
49+
50+All communications in Urbit over the [Ames](@/docs/glossary/ames.md) network
51+are end-to-end encrypted, and thus your ship stores its own public/private pair
52+of _networking keys_ utilized for encryption and authentication. Networking keys
53+for all ship types are stored within the ship's [Jael](@/docs/glossary/jael.md)
54+[vane](@/docs/glossary/vane.md).
55+
56+For planets, stars, and galaxies, your networking public key is configured on
57+the Ethereum blockchain using one of your Azimuth private keys - either the one
58+associated to the wallet which owns the ship, or the one which holds the
59+[management proxy](@/docs/glossary/proxies.md). This is typically accomplished
60+with Bridge. Your networking private key (in the
61+[keyfile](@/docs/glossary/keyfile.md)) is a necessary input for the initial boot
62+sequence of your ship (sometime called its `%dawn`), and this is also provided
63+by Bridge.
64+
65+Public keys for moons are not tracked on the blockchain; instead they are
66+tracked by their parent ship. The networking private key is generated by the
67+parent ship and injected into the `%dawn` sequence for the moon, and its public
68+key is stored by the parent in its Jael vane. Networking keys for moons may be
69+changed by the parent ship, but not by the moon itself.
70+
71+For comets, their 128-bit `@p` name is the hash of their networking public key, and
72+the "mining" process to generate a comet consists of guessing a private key for
73+which the associated public key for which the last two bytes of their `@p`
74+matches one of the stars on the comet sponsors list downloaded during boot.
75+Thus, comets cannot change their networking keys - to get a new private
76+networking key, a new comet must be generated. For a comet to perform an initial
77+handshake with another ship, it utilizes its networking private key stored in
78+Jael to sign an unencrypted attestation packet to verify that it is the owner of
79+the associated public key. Because of this, it is currently impossible for a
80+ship to initiate communication with a comet - the comet must always be the
81+initiator. This means that ultimately two comets cannot communicate with one
82+another unless they have somehow verified each others' public keys via some
83+other method. This is merely a technical limitation imposed by the design of the
84+system, not an intentional handicapping of comet abilities. A workaround to this
85+limitation is slated to be implemented as of May 2021.
86+
87+### System components
88+
89+[Ames](@/docs/arvo/ames/ames.md) is Arvo's networking vane. All packets sent by
90+Ames are encrypted utilizing a cryptosuite found in `zuse`. The only exception
91+to this are comet self-attestation packets utilized to transmit authentication
92+of ownership of the private networking key associated to their public key. Ames
93+is responsible for encryption, decryption, and authentication of all packets. By
94+default, this utilizes AES symmetric key encryption, whose shared private key is
95+got by elliptic curve Diffie-Hellman key exchange of the ships' networking keys.
96+
97+[Jael](@/docs/arvo/jael/jael-api.md) is primarily utilized for the safe storage
98+of private networking keys and retrieval of public networking keys utilized by
99+Ames. The Jael vane of planets, stars, and galaxies are responsible for
100+distributing the public keys of their moons (ultimately via Ames).
101+
102+`zuse` is the Hoon standard library. It contains cryptographic functions which
103+are utilized by Ames. All cryptographic primitives are
104+[jetted](@/docs/vere/jetting.md) in Vere with standard vetted implementations of
105+cryptographic libraries.
106+
107+[Vere](@/docs/vere/_index.md) is Urbit's Nock runtime system, written in C. All
108+cryptographic functions implemented in Hoon are hinted to the interpreter,
109+causing it to utilize the [jet system](@/docs/vere/jetting.md) to run standard vetted cryptographic
110+libraries.
111+
112+[Azimuth](@/docs/azimuth/_index.md) is an Ethereum-based public key
113+infrastructure utilized by Urbit. `azimuth-tracker` obtains networking public
114+keys for planets, stars, and galaxies from this store, which are then stored in
115+Jael and utilized by Ames for end-to-end encrypted communication.
116+