@@ -9,7 +9,7 @@ overview of where cryptographic methods are utilized in Arvo, what they are, and
9how they are implemented.
9how they are implemented.
11This document does not describe any algorithmic details of cryptographic
11This 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
13hashing - see [Insecure Hashing](@/docs/hoon/reference/stdlib/2e.md) and [SHA
13hashing - see [Insecure Hashing](@/docs/hoon/reference/stdlib/2e.md) and [SHA
14Hash Family](@/docs/reference/stdlib/3d.md) for reference material on hash
14Hash Family](@/docs/reference/stdlib/3d.md) for reference material on hash
15functions in the standard library.
15functions in the standard library.
@@ -55,12 +55,16 @@ default, all packets are encrypted with AES symmetric key encryption, whose key
55is got by Diffie-Hellman key exchange, with public/private keys generated using
55is got by Diffie-Hellman key exchange, with public/private keys generated using
56elliptic curve ed25519.
56elliptic curve ed25519.
58−### +crypto-core
58+### +crypto-core {#crypto-core}
60−The `+crypto-core` is an `+acru:ames`, a
60+The `+crypto-core` is an `+acru:ames` core, a
61[lead](@/docs/hoon/reference/advanced.md#dry-polymorphism-and-core-nesting-rules)
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
62+interface core for asymmetric cryptosuites found in `sys/zuse.hoon` which
63−handles encryption and signing.
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.
66 ++ acru $_ ^? :: asym cryptosuite
70 ++ acru $_ ^? :: asym cryptosuite
@@ -88,6 +92,40 @@ handles encryption and signing.
88 -- ::acru ::
92 -- ::acru ::
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.
102+This core is used for the standard asymmetric cryptographic operations: encrypting
103+(`+seal`), signing (`+sign`), authenticating (`+sure`), and decrypting (`+tear`).
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.
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
123+#### `+de`, `+dy`, `+en`
125+These arms are for symmetric encryption and decryption. In case of failure,
126+`+de` returns null and `+dy` crashes.
91### Diffie-Hellman key exchange {#key-exchange}
129### Diffie-Hellman key exchange {#key-exchange}
93For each `@p` a given ship has met, `$ames-state` contains a `$peer-state`,
131For each `@p` a given ship has met, `$ames-state` contains a `$peer-state`,
@@ -129,27 +167,184 @@ with a non-comet.
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.
132−### `++ed:crypto` {#ed}
174+### `+ed:crypto` {#ed}
134See also the section on Ed25519 for [Vere](#vere-ed).
176See also the section on Ed25519 for [Vere](#vere-ed).
136−### `++aes:crypto` {#aes}
178+### `+aes:crypto` {#aes}
138See also the section on AES SIV for [Vere](#vere-aes).
180See also the section on AES SIV for [Vere](#vere-aes).
140−### `++crub:crypto` {#crub}
182+### `+crub:crypto` {#crub}
142−This core implements [Suite B
184+`+crub:crypto` is a gate which creates an `+acru` core that implements [Suite B
143Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).
185Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).
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
187+It utilizes AES symmetric key encryption and decryption from `+aes:crypto`
188+implemented using the Diffie-Hellman key exchange protocol, elliptic curve
147−signature algorithm (ECDSA) signing and verification (`+sign` and `+sure`), and
189+digital signature algorithm (ECDSA) signing and verification with `+ed:crypto`,
148−elliptic curve Diffie-Hellman key generation (`+pit:nu`).
190+and generates public/private key pairs using elliptic curve cryptography with
193+`+crub:crypto` is called with public encryption and authentication keys and
194+optional secret encryption and authentication keys.
198+ =| [pub=[cry=@ sgn=@] sek=(unit [cry=@ sgn=@])]
202+`+crub` cores are typically not created by directly calling the gate, but
203+instead using one of the constructors in `+nu:crub`.
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.
217+Crashes if `sek` is null.
227+Signs message `msg=@` using the secret authentication key `sgn.u.sek`, then forms a
228+cell `[signed-message msg]` and `+jam`s it.
230+Crashes if `sek` is null.
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.
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.
259+Crashes if `sek` is null.
269+`+cue`s `txt` then decrypts with the symmetric key `key` using `de:sivc:aes`.
270+Returns null in case of failure.
275+ ++ dy :: need decrypt
280+Same as `+dy`, but crashes in case of failure.
289+Encrypts `msg` with the symmetric key `key` using `en:sivc:aes`, then `+jam`s
294+Returns the fingerprint (SHA-256) of `+pub:ex`.
298+Returns the fingerprint (SHA-256) of `+sec:ex`. Crashes if `sek` is null.
302+Returns the concatenation of `sgn.pub` and `cry.pub`.
306+Returns the concatenation of `sgn.u.sek` and `cry.u.sek`.
311+ ++ pit :: create keypair
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
321+This is how one typically generates a brand new `+crub` core for signing and
322+encrypting your own messages.
327+ ++ nol :: activate secret
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.
339+ ++ com :: activate public
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`.
152−### `++secp:crypto` {#secp}
347+### `+secp:crypto` {#secp}
154Utilized for secp256k1 (Ethereum public and private keys).
349Utilized for secp256k1 (Ethereum public and private keys).