@@ -0,0 +1,115 @@
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 utilize 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) networking
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 vane.
54+
55+For planets, stars, and galaxies, your private networking key is a
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
59+keys - either the one associated to the wallet which owns the ship, or the one
60+which holds the management proxy.
61+
62+For moons, the private networking key is generated by the parent ship and
63+injected into the `%dawn` sequence for the moon, and its public key is stored by
64+the parent in its Jael vane. Moon networking keys may be changed by the parent
65+ship, but not by the moon itself.
66+
67+For comets, their 128-bit `@p` name is actually their public key, and the
68+"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
70+to assist its peer discovery process. Thus, comets cannot change their
71+networking keys - to get a new private networking key, a new comet must be
72+generated. A comet utilizes its private networking key stored in Jael to sign an
73+unencrypted attestation packet to verify that it is the owner of the associated
74+public key. Because of this, it is currently impossible for a ship to initiate
75+communication with a comet - the comet must always be the initiator. This means
76+that ultimately two comets cannot communicate with one another unless they have
77+somehow verified each others' public keys via some other method. This is merely
78+a technical limitation imposed by the design of the system, not an intentional
79+handicapping of comet abilities. It is expected that this limitation will
80+someday be lifted.
81+
82+### System components
83+
84+[Ames](@/docs/arvo/ames/ames.md) is Arvo's networking vane. All packets sent by
85+Ames are encrypted utilizing a cryptosuite found in `zuse`. The only exception
86+to this are comet self-attestation packets utilized to transmit authentication
87+of ownership of the private networking key associated to their public key. Ames
88+is responsible for encryption, decryption, and authentication of all packets. By
89+default, this utilizes AES symmetric key encryption, whose shared private key is
90+got by elliptic curve Diffie-Hellman key exchange of the ships' networking keys.
91+
92+[Jael](@/docs/arvo/jael/jael-api.md) is primarily utilized for the safe storage
93+of private networking keys and retrieval of public networking keys utilized by
94+Ames. The Jael vane of planets, stars, and galaxies are responsible for
95+distributing the public keys of their moons (ultimately via Ames).
96+
97+`zuse` is the Hoon standard library. It contains cryptographic functions which
98+are utilized by Ames. All cryptographic primitives are
99+[jetted](@/docs/vere/jetting.md) in Vere with standard vetted implementations of
100+cryptographic libraries.
101+
102+[Vere](@/docs/vere/_index.md) is Urbit's Nock runtime system, written in C.
103+Correct implementation of cryptographic libraries is difficult, and so all
104+cryptographic functions implemented in Hoon are hinted to the interpreter to run
105+vetted cryptographic libraries reviewed by experts instead.
106+
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+
112+
113+
114+
115+