@@ -0,0 +1,115 @@
7+Cryptography is central to the operation of Urbit. This section gives an
8+overview of where cryptographic methods are utilized in Arvo, Azimuth, and Vere,
9+what they are, and how they are implemented.
11+This document does not describe any algorithmic details of cryptographic
12+functions, only how they are utilized. This document also does not yet cover
13+hashing - see [Insecure Hashing](@/docs/hoon/reference/stdlib/2e.md) and [SHA
14+Hash Family](@/docs/reference/stdlib/3d.md) for reference material on hash
15+functions in the standard library.
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.
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
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
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.
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.
53+For more information on the usage of these keys and the associated proxies, see
54+the [Azimuth documentation](@/docs/azimuth/azimuth.md).
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).
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.
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.
75+For comets, their 128-bit `@p` name is actually their public key, and the
76+"mining" process to generate a comet consists of guessing a private key for
77+which the associated public key has a galaxy that has already been pre-assigned
78+to assist its peer discovery process. Thus, comets cannot change their
79+networking keys - to get a new private networking key, a new comet must be
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 their public
87+key. Ames is responsible for encryption and decryption of all packets. By
88+default, this utilizes AES symmetric key encryption, whose shared private key is
89+got by elliptic curve Diffie-Hellman key exchange.
91+`zuse` is the Hoon standard library. It contains cryptographic primitives which
92+are utilized by Ames. All cryptographic primitives are
93+[jetted](@/docs/vere/jetting.md) in Vere with standard vetted implementations of
94+cryptographic libraries.
96+[Vere](@/docs/vere/_index.md) is Urbit's Nock runtime system, written in C.
97+Correct implementation of cryptographic libraries is difficult, and so all
98+cryptographic primitives implemented in Hoon actually hinted to the interpreter
99+to run vetted cryptographic libraries reviewed by experts instead.
101+[Jael](@/docs/arvo/jael/jael-api.md) is primarily utilized for the safe storage
102+of private keys and retrieval of public keys utilized by Ames. The Jael vane of
103+a planet is responsible for distributing the public keys of its moons
104+(ultimately via Ames), while the Jael vane of a comet is responsible for
105+distributing its own public key (also ultimately via Ames).
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. It is important to note that the
111+private keys which generate the wallet that holds ownership of your Urbit ID and
112+its proxies are not stored anywhere on your ship.