@@ -4,250 +4,50 @@ weight = 10
44template = "doc.html"
55+++
66
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.
10−
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.
7+This is a summary of the cryptography functions found in `sys/zuse.hoon`, Arvo's
8+standard library.
169
1710## Summary
1811
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.
22−
23−### Types of keys
24−
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
27−cryptography.
28−
29−#### Azimuth keys
30−
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
41−your _Azimuth keys_.
42−
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.
47−
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.
52−
53−For more information on the usage of these keys and the associated proxies, see
54−the [Azimuth documentation](@/docs/azimuth/azimuth.md).
55−
56−#### Networking keys
57−
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).
62−
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.
69−
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.
74−
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
80−generated.
81−
82−### System components
83−
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.
90−
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.
95−
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.
100−
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).
106−
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.
113−
114−## Ames
115−
116−The `$ames-state` includes a `+crypto-core`, an interface core into which one of
117−the cryptosuites in `zuse` may be implemented. The suite utilized by the
118−`+crypto-core` is used to encrypt all communications utilized by Ames. By
119−default, all packets are encrypted with AES symmetric key encryption, whose key
120−is got by Diffie-Hellman key exchange, with public/private keys generated using
121−elliptic curve ed25519.
122−
123−### +crypto-core {#crypto-core}
124−
125−The `+crypto-core` is an `+acru:ames` core, a
126−[lead](@/docs/hoon/reference/advanced.md#dry-polymorphism-and-core-nesting-rules)
127−interface core for asymmetric cryptosuites found in `sys/zuse.hoon` which
128−handles encryption, decryption, signing, and verifying. In practice, the only
129−cryptosuite in use is [`+crub:crypto`](#crub), which implements [Suite B
130−Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography). Under
131−most circumstances, all asymmetric encryption- and signing-related tasks done
132−within Urbit should be mediated via an `+acru` interface.
133−
134−```hoon
135− ++ acru $_ ^? :: asym cryptosuite
136− |% :: opaque object
137− ++ as ^? :: asym ops
138− |% ++ seal |~([a=pass b=@] *@) :: encrypt to a
139− ++ sign |~(a=@ *@) :: certify as us
140− ++ sure |~(a=@ *(unit @)) :: authenticate from us
141− ++ tear |~([a=pass b=@] *(unit @)) :: accept from a
142− -- ::as ::
143− ++ de |~([a=@ b=@] *(unit @)) :: symmetric de, soft
144− ++ dy |~([a=@ b=@] *@) :: symmetric de, hard
145− ++ en |~([a=@ b=@] *@) :: symmetric en
146− ++ ex ^? :: export
147− |% ++ fig *@uvH :: fingerprint
148− ++ pac *@uvG :: default passcode
149− ++ pub *pass :: public key
150− ++ sec *ring :: private key
151− -- ::ex ::
152− ++ nu ^? :: reconstructors
153− |% ++ pit |~([a=@ b=@] ^?(..nu)) :: from [width seed]
154− ++ nol |~(a=ring ^?(..nu)) :: from ring
155− ++ com |~(a=pass ^?(..nu)) :: from pass
156− -- ::nu ::
157− -- ::acru ::
158−```
159−
160−As the `+acru` core is merely an interface, the details on how it is utilized
161−may vary according to the cryptosuite implemented in it. We summarize what each
162−core is utilized for here, but see [`crub:crypto`](#crub) for more details on
163−how the specific cryptosuite utilized by Ames is implemented.
164−
165−#### `+as:acru`
166−
167−This core is used for the standard asymmetric cryptographic operations: encrypting
168−(`+seal`), signing (`+sign`), authenticating (`+sure`), and decrypting (`+tear`).
169−
170−#### `+ex:acru`
171−
172−This core stores keys and their fingerprints. `+sec` is the secret key (which
173−may be empty), `+pub` is the public key associated to the secret key, `+pac` is
174−the fingerprint associated to the secret key, and `+fig` is the fingerprint
175−associated to the public key. We note that when the core contains both
176−encryption and authentication keys, they are typically concatenated to be
177−returned as a single atom.
178−
179−#### `+nu:acru`
180−
181−This core contains constructors for the `+acru` core. `+pit:nu` is used to
182−construct an `+acru` core with both a private and public key (i.e. both
183−`+sec:ex` and `pub:ex` are set) from a bitlength and seed. `+nol:nu` can then be
184−called from an `+acru` core created with `+pit:nu` to get an `+acru` core with
185−only the secret key, while `+com:nu` can be called to get an `+acru` core with
186−only the public key.
187−
188−#### `+de`, `+dy`, `+en`
189−
190−These arms are for symmetric encryption and decryption. In case of failure,
191−`+de` returns null and `+dy` crashes.
192−
193−
194−### Diffie-Hellman key exchange {#key-exchange}
195−
196−For each `@p` a given ship has met, `$ames-state` contains a `$peer-state`,
197−inside which the `$symmetric-key` (an atom which nests under `@uw`) utilized for
198−encrypting all Ames packets shared between the two ships. The `symmetric-key` is
199−derived using `shar:ed:crypto` found in `sys/zuse.hoon`, which is an arm
200−utilized for generating the symmetric key for elliptic curve Diffie-Hellman key
201−exchange with [curve25519](https://en.wikipedia.org/wiki/Curve25519); see
202−[below](#ed) for more information on the `ed:crypto` core.
203−
204−### Packet encryption
205−
206−The encrypted payload of each packet is a `$shut-packet`, which is the `+jam` of
207−a cell with the `bone`, message number, and message fragment or ack (see
208−[Ames](@/docs/ames/ames.md) for more information on packet structure). It is
209−encrypted using `++sivc:aes:crypto` found in `sys/zuse.hoon`, which is an arm
210−utilized for 256-bit AES SIV symmetric encryption; see [below](#aes) for more
211−information on the `aes:crypto` core.
212−
213−### Comet self-attestation
214−
215−Recall that the `@p` of a comet is simply casting their 128-bit public key as a
216−`@p`. Since the public key of a comet is not stored on Azimuth, a comet proves
217−its identity with an "attestation packet". This is an unencrypted packet whose
218−payload contains the comet's signature created with its private key. This is the
219−only situation in which a ship will send an unencrypted packet. The signature is
220−generated with `sign:as:acru`, and thus which signature algorithm is utilized
221−depends on the `+crypto-core`.
222−
223−Upon hearing an attestation packet, the receiving ship will generate a symmetric
224−key for communications with the comet, according to the [key
225−exchange](#key-exchange) protocol.
226−
227−The fact that the first packet exchanged between a comet and another ship must
228−be an attestation packet is why comets are unable to initiate communication with
229−one another, and also why comets must be the first to initiate communication
230−with a non-comet.
231−
232−
233−## `zuse`
234−
23512`zuse` contains several cryptosuites. The only ones currently in use are
23613`+ed:crypto`, `+aes:crypto`, and `+crub:crypto`, with the latter being the
237−only one which is implementable as an `+acru` core.
14+only one which is implementable as an [`+acru:ames`
15+core](@/docs/arvo/ames/cryptography/#crypto-core).
23816
23917### `+ed:crypto` {#ed}
24018
241−See also the section on Ed25519 for [Vere](#vere-ed).
19+This core contains cryptographic primitives and helper functions for elliptic
20+curve cryptography with [Curve25519](https://en.wikipedia.org/wiki/Curve25519).
21+
22+`+ed:crypto` is used to generate public/private keypairs from a seed for use
23+with [elliptic curve
24+Diffie-Hellman](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman)
25+key agreements as well as [Elliptic Curve Digital Signature
26+Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm).
27+These functionalities are ultimately utilized by [`+crub:crypto`](#crub), the
28+only cryptosuite which [Ames](@/docs/arvo/ames/ames.md) makes use of.
29+
30+Most gates in `+ed:crypto` are [jetted](@/docs/vere/jetting.md), meaning that an
31+external reference library is utilized whenever these functions are called,
32+rather than running in Nock natively. See the [Vere
33+documentation](@/docs/vere/cryptography/#ed) for more information about the
34+library utilized by jets.
24235
24336### `+aes:crypto` {#aes}
24437
245−See also the section on AES SIV for [Vere](#vere-aes).
38+This core contains cryptographic primitives and helper functions for
39+[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) symmetric key
40+encryption and decryption. As is the case with `ed:crypto`, these
41+functionalities are utilized by [`+crub:crypto`](#crub), and most functions are
42+jetted. See also the Vere documentation on [AES
43+SIV](@/docs/vere/cryptography/#aes) for more information about the library
44+utilized by jets.
24645
24746### `+crub:crypto` {#crub}
24847
249−`+crub:crypto` is a gate which creates an `+acru` core that implements [Suite B
250−Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).
48+`+crub:crypto` implements an
49+[`+acru:ames`](@/docs/arvo/ames/cryptography/#crypto-core) core that implements
50+[Suite B Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).
25151
25252It utilizes AES symmetric key encryption and decryption from `+aes:crypto`
25353implemented using the Diffie-Hellman key exchange protocol, elliptic curve
@@ -413,46 +213,3 @@ Takes in a `pass` from a `+pub:ex:crub` and generates a new `+crub` core with
413213
414214Utilized for secp256k1 (Ethereum public and private keys).
415215
416−
417−## Vere
418−
419−All cryptographic primitives utilized by Arvo are
420−[jetted](@/docs/vere/jetting.md). This is done for performance-related reasons
421−in other parts of the system, but for cryptography this is also extremely
422−important because it allows us to utilize standard reference implementations for
423−the primitives written in C.
424−
425−All jets related to encryption may be found in `pkg/urbit/jets/e/`.
426−
427−In this section we review what specific implementations are utilized.
428−
429−### Ed25519 {#vere-ed}
430−
431−Urbit implements [Ed25519](http://ed25519.cr.yp.to/) based on the SUPERCOP
432−"ref10" implementation. Additionally there is key exchanging and scalar addition
433−included to further aid building a PKI using Ed25519. All code is licensed under
434−the permissive zlib license.
435−
436−All code is pure ANSI C without any dependencies, except for the random seed
437−generation which uses standard OS cryptography APIs (CryptGenRandom on Windows,
438−`/dev/urandom` on nix).
439−
440−### AES SIV {#vere-aes}
441−
442−The library we utilize for AES SIV is an
443−[RFC5297](https://tools.ietf.org/html/rfc5297)-compliant C implementation of
444−AES-SIV written by Daniel Franke on behalf of [Akamai
445−Technologies](https://www.akamai.com). It is published under the [Apache License
446−(v2.0)](https://www.apache.org/licenses/LICENSE-2.0). It uses OpenSSL for the
447−underlying [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) and
448−[CMAC](https://en.wikipedia.org/wiki/One-key_MAC) implementations and follows a
449−similar interface style.
450−
451−While the jets are found in `pkg/urbit/jets/e`, the statically-linked package is
452−found at `pkg/libas_siv/`.
453−
454−
455−
456−
457−
458−