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.