git.iko.soy/urbit.org
on 514b5fc help sign in
urbit.org/content/docs/arvo/reference/cryptography.md
222 lines 7.2 kB history raw
1+++
2title = "Cryptography"
3weight = 10
4template = "doc.html"
5+++
7This is a summary of the cryptography functions found in `sys/zuse.hoon`, Arvo's
8standard library. This page currently only documents cryptographic functions
9directly utilized by [Ames](/docs/arvo/ames/ames). `zuse` also contains
10cryptographic functions relevant to Ethereum such as the `+keccak:crypto` core,
11but they are currently undocumented.
13Documentation for [Insecure Hashing](/docs/hoon/reference/stdlib/2e) and the
14[SHA Hash Family](/docs/hoon/reference/stdlib/3d) is found in the Hoon standard
15library reference.
17## Summary
19`zuse` contains several cryptosuites. The ones utilized by Ames are
20[`+ed:crypto`](#ed), [`+aes:crypto`](#aes), and [`+crub:crypto`](#crub), with
21the latter being the only one which is implemented as an [`+acru:ames`](/docs/arvo/ames/cryptography#crypto-core)-shaped core.
23## `+crub:crypto` {#crub}
25`+crub:crypto` implements an
26[`+acru:ames`](/docs/arvo/ames/cryptography#crypto-core) core that implements
27[Suite B Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).
29It utilizes AES symmetric key encryption and decryption from [`+aes:crypto`](#aes)
30implemented using the Diffie-Hellman key exchange protocol, elliptic curve
31digital signature algorithm (ECDSA) signing and verification with [`+ed:crypto`](#ed),
32and generates public/private key pairs using elliptic curve cryptography with
33`+ed:crypto`.
35A `+crub:crypto` core's payload contains public encryption and authentication
36keys and optional secret encryption and authentication keys.
38```hoon
39 ++ crub !:
40 ^- acru
41 =| [pub=[cry=@ sgn=@] sek=(unit [cry=@ sgn=@])]
42 |%
43 ...
44```
46`+crub` cores (because they follow the `+acru` interface) are typically created using one of the constructors in [`+nu:crub`](#nu).
48### `+seal:as`
50```hoon
51 ++ seal ::
52 |= [bpk=pass msg=@]
53 ...
54```
56Forms a symmetric key using Diffie-Hellman key exchange with the secret key
57stored at `sgn.u.sek` and a public key `bpk`. Then `+sign`s `msg`, encrypts the
58signed message using `+en:siva:aes` with the symmetric key, and then `+jam`s it.
60Crashes if `sek` is null.
62### `+sign:as` {#sign-as}
64```hoon
65 ++ sign ::
66 |= msg=@
67 ...
68```
70Signs message `msg=@` using the secret authentication key `sgn.u.sek`, then forms a
71cell `[signed-message msg]` and `+jam`s it.
73Crashes if `sek` is null.
75### `+sure:as`
77```hoon
78 ++ sure ::
79 |= txt=@
80 ...
81```
83`+cue`s `txt` to get a signature `sig=@` and message `msg=@`. Verifies that
84`sig` was `msg` signed using the secret key associated to the public key stored
85at `sgn.pub`. Returns `(unit msg)` if so, null otherwise.
87### `+tear:as`
89```hoon
90 ++ tear ::
91 |= [bpk=pass txt=@]
92 ...
93```
95Forms a secret symmetric key using Diffie-Hellman key exchange using the secret
96key `cry.u.sek` and encryption key part of the public key `bpk` (which here is a
97concatenation of both the encryption and authentication public keys). `+cue`s
98`txt` and decrypts it using `+de:siva:aes` with the symmetric key. If decryption
99is successful, verifies the decrypted message using authentication key part of
100`bpk`, and returns it if so. Returns null otherwise.
102Crashes if `sek` is null.
104### `+de`
106```hoon
107 ++ de :: decrypt
108 |= [key=@J txt=@]
109 ...
110```
112`+cue`s `txt` then decrypts with the symmetric key `key` using `+de:sivc:aes`.
113Returns null in case of failure.
115### `+dy`
117```hoon
118 ++ dy :: need decrypt
119 |= [key=@J cph=@]
120 ...
121```
123Same as `+dy`, but crashes in case of failure.
125### `+en` {#en}
127```hoon
128 ++ en :: encrypt
129 |= [key=@J msg=@]
130```
132Encrypts `msg` with the symmetric key `key` using `en:sivc:aes`, then `+jam`s
133it.
135### `+fig:ex`
137Returns the fingerprint (SHA-256) of `+pub:ex`.
139### `+pac:ex`
141Returns the fingerprint (SHA-256) of `+sec:ex`. Crashes if `sek` is null.
143### `+pub:ex`
145Returns the concatenation of `sgn.pub` and `cry.pub`.
147### `+sec:ex`
149Returns the concatenation of `sgn.u.sek` and `cry.u.sek`.
151### `+pit:nu` {#nu}
153```hoon
154 ++ pit :: create keypair
155 |= [w=@ seed=@]
156 ...
157```
159Creates a `+crub` core with encryption and authentication public/private keypairs
160generated from a bitwidth `w` and `seed`. The private keys are generated with
161SHA-512, while `+puck:ed:crypto` is used to derive the public keys from the
162private keys.
164This is how one typically generates a brand new `+crub` core for signing and
165encrypting your own messages.
167### `+nol:nu`
169```hoon
170 ++ nol :: activate secret
171 |= a=ring
172 ...
173```
175Takes in a `ring` from a `+sec:ex:crub` and generates a new `+crub` core with
176`sek` taken from `+sec:ex` and `pub` generated with `+puck:ed:crypto`. Crashes
177if `+sec:ex` is not a `+crub` secret key.
179### `+com:nu`
181```hoon
182 ++ com :: activate public
183 |= a=pass
184 ...
185```
187Takes in a `pass` from a `+pub:ex:crub` and generates a new `+crub` core with
188`pub` taken from `+pub:ex` and null `sek`.
190## `+ed:crypto` {#ed}
192This core contains cryptographic primitives and helper functions for elliptic
193curve cryptography with [Curve25519](https://en.wikipedia.org/wiki/Curve25519).
195`+ed:crypto` is primarily used to generate public/private keypairs from a seed
196for use with [elliptic curve
197Diffie-Hellman](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman)
198key agreements as well as [Elliptic Curve Digital Signature
199Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm).
200These functionalities are ultimately utilized by [`+crub:crypto`](#crub), the
201only cryptosuite which [Ames](/docs/arvo/ames/ames) makes use of.
203Most gates in `+ed:crypto` are [jetted](/docs/vere/jetting), meaning that an
204external reference library is utilized whenever these functions are called,
205rather than running in Nock natively. See the [Vere
206documentation](/docs/vere/cryptography#ed) for more information about the
207library utilized by jets.
209## `+aes:crypto` {#aes}
211This core contains cryptographic primitives and helper functions for
212[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) symmetric key
213encryption and decryption. As is the case with `ed:crypto`, these
214functionalities are utilized by [`+crub:crypto`](#crub), and most gates are
215jetted. See also the Vere documentation on [AES
216SIV](/docs/vere/cryptography#aes) for more information about the library
217utilized by jets.
219This core contains several doors, each one used for a different variation of AES
220according to key size and mode. The only ones currently in use are
221`+siva:aes:crypto` and `+sivc:aes:crypto`, which are 128-bit and
222256-bit modes of [`AES-SIV`](https://www.aes-siv.com) respectively.