@@ -1,115 +0,0 @@
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.