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