@@ -9,7 +9,7 @@ overview of where cryptographic methods are utilized in Arvo, what they are, and
99how they are implemented.
1010
1111This document does not describe any algorithmic details of cryptographic
12−functions, only how they are utilized. This document also does not cover
12+functions, only how they are utilized. This document also does not yet cover
1313hashing - see [Insecure Hashing](@/docs/hoon/reference/stdlib/2e.md) and [SHA
1414Hash Family](@/docs/reference/stdlib/3d.md) for reference material on hash
1515functions in the standard library.
@@ -55,12 +55,16 @@ default, all packets are encrypted with AES symmetric key encryption, whose key
5555is got by Diffie-Hellman key exchange, with public/private keys generated using
5656elliptic curve ed25519.
5757
58−### +crypto-core
58+### +crypto-core {#crypto-core}
5959
60−The `+crypto-core` is an `+acru:ames`, a
60+The `+crypto-core` is an `+acru:ames` core, a
6161[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.
62+interface core for asymmetric cryptosuites found in `sys/zuse.hoon` which
63+handles encryption, decryption, signing, and verifying. In practice, the only
64+cryptosuite in use is [`+crub:crypto`](#crub), which implements [Suite B
65+Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography). Under
66+most circumstances, all asymmetric encryption- and signing-related tasks done
67+within Urbit should be mediated via an `+acru` interface.
6468
6569```hoon
6670 ++ acru $_ ^? :: asym cryptosuite
@@ -88,6 +92,40 @@ handles encryption and signing.
8892 -- ::acru ::
8993```
9094
95+As the `+acru` core is merely an interface, the details on how it is utilized
96+may vary according to the cryptosuite implemented in it. We summarize what each
97+core is utilized for here, but see [`crub:crypto`](#crub) for more details on
98+how the specific cryptosuite utilized by Ames is implemented.
99+
100+#### `+as:acru`
101+
102+This core is used for the standard asymmetric cryptographic operations: encrypting
103+(`+seal`), signing (`+sign`), authenticating (`+sure`), and decrypting (`+tear`).
104+
105+#### `+ex:acru`
106+
107+This core stores keys and their fingerprints. `+sec` is the secret key (which
108+may be empty), `+pub` is the public key associated to the secret key, `+pac` is
109+the fingerprint associated to the secret key, and `+fig` is the fingerprint
110+associated to the public key. We note that when the core contains both
111+encryption and authentication keys, they are typically concatenated to be
112+returned as a single atom.
113+
114+#### `+nu:acru`
115+
116+This core contains constructors for the `+acru` core. `+pit:nu` is used to
117+construct an `+acru` core with both a private and public key (i.e. both
118+`+sec:ex` and `pub:ex` are set) from a bitlength and seed. `+nol:nu` can then be
119+called from an `+acru` core created with `+pit:nu` to get an `+acru` core with
120+only the secret key, while `+com:nu` can be called to get an `+acru` core with
121+only the public key.
122+
123+#### `+de`, `+dy`, `+en`
124+
125+These arms are for symmetric encryption and decryption. In case of failure,
126+`+de` returns null and `+dy` crashes.
127+
128+
91129### Diffie-Hellman key exchange {#key-exchange}
92130
93131For each `@p` a given ship has met, `$ames-state` contains a `$peer-state`,
@@ -129,27 +167,184 @@ with a non-comet.
129167
130168## `zuse`
131169
132−### `++ed:crypto` {#ed}
170+`zuse` contains several cryptosuites. The only ones currently in use are
171+`+ed:crypto`, `+aes:crypto`, and `+crub:crypto`, with the latter being the
172+only one which is implementable as an `+acru` core.
173+
174+### `+ed:crypto` {#ed}
133175
134176See also the section on Ed25519 for [Vere](#vere-ed).
135177
136−### `++aes:crypto` {#aes}
178+### `+aes:crypto` {#aes}
137179
138180See also the section on AES SIV for [Vere](#vere-aes).
139181
140−### `++crub:crypto` {#crub}
182+### `+crub:crypto` {#crub}
141183
142−This core implements [Suite B
184+`+crub:crypto` is a gate which creates an `+acru` core that implements [Suite B
143185Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).
144186
145−It makes use of `+ed:crypto` and `+aes:crypto` to implement AES symmetric key
146−encryption and decryption (`+seal` and `+tear`), elliptic curve digital
147−signature algorithm (ECDSA) signing and verification (`+sign` and `+sure`), and
148−elliptic curve Diffie-Hellman key generation (`+pit:nu`).
187+It utilizes AES symmetric key encryption and decryption from `+aes:crypto`
188+implemented using the Diffie-Hellman key exchange protocol, elliptic curve
189+digital signature algorithm (ECDSA) signing and verification with `+ed:crypto`,
190+and generates public/private key pairs using elliptic curve cryptography with
191+`+ed:crypto`.
192+
193+`+crub:crypto` is called with public encryption and authentication keys and
194+optional secret encryption and authentication keys.
195+```hoon
196+ ++ crub !:
197+ ^- acru
198+ =| [pub=[cry=@ sgn=@] sek=(unit [cry=@ sgn=@])]
199+ |%
200+ ...
201+```
202+`+crub` cores are typically not created by directly calling the gate, but
203+instead using one of the constructors in `+nu:crub`.
204+
205+#### `+seal:as`
206+
207+```hoon
208+ ++ seal ::
209+ |= [bpk=pass msg=@]
210+ ...
211+```
212+
213+Forms a symmetric key using Diffie-Hellman key exchange with the secret key
214+stored at `sgn.u.sek` and a public key `bpk`. Then `+sign`s `msg`, encrypts the
215+signed message using `+en:siva:aes` with the symmetric key, and then `+jam`s it.
216+
217+Crashes if `sek` is null.
218+
219+#### `+sign:as`
220+
221+```hoon
222+ ++ sign ::
223+ |= msg=@
224+ ...
225+```
226+
227+Signs message `msg=@` using the secret authentication key `sgn.u.sek`, then forms a
228+cell `[signed-message msg]` and `+jam`s it.
229+
230+Crashes if `sek` is null.
231+
232+#### `+sure:as`
233+
234+```hoon
235+ ++ sure ::
236+ |= txt=@
237+ ...
238+```
239+
240+`+cue`s `txt` to get a signature `sig=@` and message `msg=@`. Verifies that
241+`sig` was `msg` signed using the secret key associated to the public key stored
242+at `sgn.pub`. Returns `(unit msg)` if so, null otherwise.
243+
244+#### `+tear:as`
245+
246+```hoon
247+ ++ tear ::
248+ |= [bpk=pass txt=@]
249+ ...
250+```
251+
252+Forms a secret symmetric key using Diffie-Hellman key exchange using the secret
253+key `cry.u.sek` and encryption key part of the public key `bpk` (which here is a
254+concatenation of both the encryption and authentication public keys). `+cue`s
255+`txt` and decrypts it using `+de:siva:aes` with the symmetric key. If decryption
256+is successful, verifies the decrypted message using authentication key part of
257+`bpk`, and returns it if so. Returns null otherwise.
258+
259+Crashes if `sek` is null.
260+
261+#### `+de`
262+
263+```hoon
264+ ++ de :: decrypt
265+ |= [key=@J txt=@]
266+ ...
267+```
268+
269+`+cue`s `txt` then decrypts with the symmetric key `key` using `de:sivc:aes`.
270+Returns null in case of failure.
271+
272+#### `+dy`
273+
274+```hoon
275+ ++ dy :: need decrypt
276+ |= [key=@J cph=@]
277+ ...
278+```
279+
280+Same as `+dy`, but crashes in case of failure.
281+
282+#### `+en`
283+
284+```hoon
285+ ++ en :: encrypt
286+ |= [key=@J msg=@]
287+```
288+
289+Encrypts `msg` with the symmetric key `key` using `en:sivc:aes`, then `+jam`s
290+it.
291+
292+#### `+fig:ex`
293+
294+Returns the fingerprint (SHA-256) of `+pub:ex`.
295+
296+#### `+pac:ex`
297+
298+Returns the fingerprint (SHA-256) of `+sec:ex`. Crashes if `sek` is null.
299+
300+#### `+pub:ex`
301+
302+Returns the concatenation of `sgn.pub` and `cry.pub`.
303+
304+#### `+sec:ex`
305+
306+Returns the concatenation of `sgn.u.sek` and `cry.u.sek`.
307+
308+#### `+pit:nu`
309+
310+```hoon
311+ ++ pit :: create keypair
312+ |= [w=@ seed=@]
313+ ...
314+```
315+
316+Creates a `+crub` core with encryption and authentication public/private keypairs
317+generated from a bitwidth `w` and `seed`. The private keys are generated with
318+SHA-512, while `+puck:ed:crypto` is used to derive the public keys from the
319+private keys.
320+
321+This is how one typically generates a brand new `+crub` core for signing and
322+encrypting your own messages.
323+
324+#### `+nol:nu`
325+
326+```hoon
327+ ++ nol :: activate secret
328+ |= a=ring
329+ ...
330+```
331+
332+Takes in a `ring` from a `+sec:ex:crub` and generates a new `+crub` core with
333+`sek` taken from `+sec:ex` and `pub` generated with `+puck:ed:crypto`. Crashes
334+if `+sec:ex` is not a `+crub` secret key.
335+
336+#### `+com:nu`
337+
338+```hoon
339+ ++ com :: activate public
340+ |= a=pass
341+ ...
342+```
149343
150−It is used ...
344+Takes in a `pass` from a `+pub:ex:crub` and generates a new `+crub` core with
345+`pub` taken from `+pub:ex` and null `sek`.
151346
152−### `++secp:crypto` {#secp}
347+### `+secp:crypto` {#secp}
153348
154349Utilized for secp256k1 (Ethereum public and private keys).
155350