Cryptography is central to the operation of Urbit. Here we give an overview of how it is utilized.
There are two categories of keys and five components of the system involved with cryptography on Urbit. We first summarize the two categories of keys and how they are utilized by each ship type, then cover how different parts of Urbit are involved in cryptography.
Types of keys
The two categories of keys are your Azimuth/Ethereum keys and your networking keys. In both cases, these are public/private key pairs utilized for public key cryptography.
Azimuth keys
Your Urbit ID exists as an ERC-721 non-fungible token on the Ethereum blockchain, and as such is contained in a wallet whose private key you possess. If you are are utilizing a master ticket, this private key is derived from a seed, which is what you use to login to Bridge. Otherwise, you have generated the key by some other process, of which there are too many to list here. Besides the private key which unlocks your ownership wallet address, you may have a few other private keys which unlock a wallet that corresponds to your ship's proxies. We refer collectively to these keys as your Azimuth keys.
Only planets, stars, and galaxies have Azimuth keys. Moons and comets do not, as they do not exist on the Ethereum blockchain.
It is important to note that no Azimuth keys are stored anywhere within your ship's pier - Ethereum and Urbit ID are entirely separate entities from Urbit itself, and so you lose access to your Azimuth private keys there is no way to retrieve them somehow from your ship.
For more information on the usage of these keys and the associated proxies, see the Azimuth documentation.
Networking keys
All communications in Urbit over the Ames network are end-to-end encrypted, and thus your ship stores its own public/private pair of networking keys utilized for encryption and authentication. Networking keys for all ship types are stored within the ship's Jael vane.
For planets, stars, and galaxies, your networking public key is configured on the Ethereum blockchain using one of your Azimuth private keys - either the one associated to the wallet which owns the ship, or the one which holds the management proxy. This is typically accomplished with Bridge. Your networking private key (in the keyfile) is a necessary input for the initial boot sequence of your ship (sometime called its %dawn), and this is also provided by Bridge.
Public keys for moons are not tracked on the blockchain; instead they are tracked by their parent ship. The networking private key is generated by the parent ship and injected into the %dawn sequence for the moon, and its public key is stored by the parent in its Jael vane. Networking keys for moons may be changed by the parent ship, but not by the moon itself.
For comets, their 128-bit @p name is the hash of their networking public key, and the "mining" process to generate a comet consists of guessing a private key for which the associated public key for which the last two bytes of their @p matches one of the stars on the comet sponsors list downloaded during boot. Thus, comets cannot change their networking keys - to get a new private networking key, a new comet must be generated. For a comet to perform an initial handshake with another ship, it utilizes its networking private key stored in Jael to sign an unencrypted attestation packet to verify that it is the owner of the associated public key. Because of this, it is currently impossible for a ship to initiate communication with a comet - the comet must always be the initiator. This means that ultimately two comets cannot communicate with one another unless they have somehow verified each others' public keys via some other method. This is merely a technical limitation imposed by the design of the system, not an intentional handicapping of comet abilities. A workaround to this limitation is slated to be implemented as of May 2021.
System components
Ames is Arvo's networking vane. All packets sent by Ames are encrypted utilizing a cryptosuite found in zuse. The only exception to this are comet self-attestation packets utilized to transmit authentication of ownership of the private networking key associated to their public key. Ames is responsible for encryption, decryption, and authentication of all packets. By default, this utilizes AES symmetric key encryption, whose shared private key is got by elliptic curve Diffie-Hellman key exchange of the ships' networking keys.
Jael is primarily utilized for the safe storage of private networking keys and retrieval of public networking keys utilized by Ames. The Jael vane of planets, stars, and galaxies are responsible for distributing the public keys of their moons (ultimately via Ames).
zuse is part of the standard library. It contains cryptographic functions which are utilized by Ames. All cryptographic primitives are jetted in Vere with standard vetted implementations of cryptographic libraries.
Vere is Urbit's Nock runtime system, written in C. All cryptographic functions implemented in Hoon are hinted to the interpreter, causing it to utilize the jet system to run standard vetted cryptographic libraries.
Azimuth is an Ethereum-based public key infrastructure utilized by Urbit. azimuth-tracker obtains networking public keys for planets, stars, and galaxies from this store, which are then stored in Jael and utilized by Ames for end-to-end encrypted communication.
Additional documentation
The following pages contained more detailed information about the cryptography utilized by each of the system components.