@@ -8,14 +8,22 @@ Cryptography is central to the operation of Urbit. This section gives an
8overview of where cryptographic methods are utilized in Arvo, what they are, and
8overview of where cryptographic methods are utilized in Arvo, what they are, and
9how they are implemented.
9how 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 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.
11There are five parts of the system involved with cryptography on Urbit. We
19There are five parts of the system involved with cryptography on Urbit. We
12summarize each component here briefly, and then continue with a more detailed
20summarize each component here briefly, and then continue with a more detailed
13exposition below.
21exposition below.
15−[Ames](@/docs/arvo/ames/ames.md) is Arvo's networking vane. Associated to each
23+[Ames](@/docs/arvo/ames/ames.md) is Arvo's networking vane. All packets sent by
16−flow is a `+crypto-core`, an interface core into which one of the cryptosuites
24+Ames are encrypted utilizing a cryptosuite found in `zuse`. Ames is responsible
17−in `zuse` may be implemented. The suite utilized by the `+crypto-core` is used
25+for encryption and decryption of all packets. By default, this utilizes AES
18−to encrypt all communications over the corresponding flow.
26+symmetric key encryption, whose key is got by elliptic curve Diffie-Hellman key exchange.
20`zuse` is the Hoon standard library. It contains cryptographic primitives which
28`zuse` is the Hoon standard library. It contains cryptographic primitives which
21may be utilized by an Ames `+crypto-core`. All cryptographic primitives are
29may be utilized by an Ames `+crypto-core`. All cryptographic primitives are
@@ -28,9 +36,101 @@ cryptographic primitives implemented in Hoon actually hint to the interpreter to
28run vetted cryptographic libraries reviewed by experts.
36run vetted cryptographic libraries reviewed by experts.
30[Jael](@/docs/arvo/jael/jael-api.md) is utilized for the safe storage and
38[Jael](@/docs/arvo/jael/jael-api.md) is utilized for the safe storage and
31−retrieval of private and public keys utilized by Ames and Azimuth.
39+retrieval of private and public keys utilized by Ames and Azimuth. The Jael vane
40+of a planet is responsible for distributing the public keys of its moons
41+(ultimately via Ames), while the Jael vane of a comet is responsible for
42+distributing its own public key (also ultimately via Ames).
33[Azimuth](@/docs/azimuth/_index.md) is Urbit's Ethereum-based public key
44[Azimuth](@/docs/azimuth/_index.md) is Urbit's Ethereum-based public key
34−infrastructure.
45+infrastructure. `azimuth-tracker` obtains public keys for planets, stars, and
46+galaxies from this store, which are then stored in Jael and utilized by Ames for
47+end-to-end encrypted communication.
51+The `$ames-state` includes a `+crypto-core`, an interface core into which one of
52+the cryptosuites in `zuse` may be implemented. The suite utilized by the
53+`+crypto-core` is used to encrypt all communications utilized by Ames. By
54+default, all packets are encrypted with AES symmetric key encryption, whose key
55+is got by Diffie-Hellman key exchange, with public/private keys generated using
56+elliptic curve ed25519.
60+The `+crypto-core` is an `+acru:ames`, a
61+[lead](@/docs/hoon/reference/advanced.md#dry-polymorphism-and-core-nesting-rules)
62+interface core for asymmetric cryptosuites found in `sys/lull.hoon` which
63+handles encryption and signing.
66+ ++ acru $_ ^? :: asym cryptosuite
69+ |% ++ seal |~([a=pass b=@] *@) :: encrypt to a
70+ ++ sign |~(a=@ *@) :: certify as us
71+ ++ sure |~(a=@ *(unit @)) :: authenticate from us
72+ ++ tear |~([a=pass b=@] *(unit @)) :: accept from a
74+ ++ de |~([a=@ b=@] *(unit @)) :: symmetric de, soft
75+ ++ dy |~([a=@ b=@] *@) :: symmetric de, hard
76+ ++ en |~([a=@ b=@] *@) :: symmetric en
78+ |% ++ fig *@uvH :: fingerprint
79+ ++ pac *@uvG :: default passcode
80+ ++ pub *pass :: public key
81+ ++ sec *ring :: private key
83+ ++ nu ^? :: reconstructors
84+ |% ++ pit |~([a=@ b=@] ^?(..nu)) :: from [width seed]
85+ ++ nol |~(a=ring ^?(..nu)) :: from ring
86+ ++ com |~(a=pass ^?(..nu)) :: from pass
91+### Diffie-Hellman key exchange {#key-exchange}
93+For each `@p` a given ship has met, `$ames-state` contains a `$peer-state`,
94+inside which the `$symmetric-key` (an atom which nests under `@uw`) utilized for
95+encrypting all Ames packets shared between the two ships. The `symmetric-key` is
96+derived using `shar:ed:crypto` found in `sys/zuse.hoon`, which is an arm
97+utilized for generating the symmetric key for elliptic curve Diffie-Hellman key
98+exchange with [curve25519](https://en.wikipedia.org/wiki/Curve25519); see
99+[below](#ed) for more information on the `ed:crypto` core.
101+### Packet encryption
103+The encrypted payload of each packet is a `$shut-packet`, which is the `+jam` of
104+a cell with the `bone`, message number, and message fragment or ack (see
105+[Ames](@/docs/ames/ames.md) for more information on packet structure). It is
106+encrypted using `++sivc:aes:crypto` found in `sys/zuse.hoon`, which is an arm
107+utilized for 256-bit AES SIV symmetric encryption; see [below](#aes) for more
108+information on the `aes:crypto` core.
110+### Comet self-attestation
112+Recall that the `@p` of a comet is simply casting their 128-bit public key as a
113+`@p`. Since the public key of a comet is not stored on Azimuth, a comet proves
114+its identity with an "attestation packet". This is an unencrypted packet whose
115+payload contains the comet's signature created with its private key. This is the
116+only situation in which a ship will send an unencrypted packet. The signature is
117+generated with `sign:as:acru`, and thus which signature algorithm is utilized
118+depends on the `+crypto-core`.
120+Upon hearing an attestation packet, the receiving ship will generate a symmetric
121+key for communications with the comet, according to the [key
122+exchange](#key-exchange) protocol.
124+The fact that the first packet exchanged between a comet and another ship must
125+be an attestation packet is why comets are unable to initiate communication with
126+one another, and also why comets must be the first to initiate communication
132+### `++ed:crypto` {#ed}
134+### `++aes:crypto` {#aes}