git.iko.soy/urbit.org
on cd23ade help sign in
urbit.org/arvo/reference/cryptography.md
220 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.md). `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.md) and the
14[SHA Hash Family](@/docs/hoon/reference/stdlib/3d.md) 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.md#crypto-core)-shaped core.
23## `+crub:crypto` {#crub}
25`+crub:crypto` implements an
26[`+acru:ames`](@/docs/arvo/ames/cryptography.md#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.
37```hoon
38 ++ crub !:
39 ^- acru
40 =| [pub=[cry=@ sgn=@] sek=(unit [cry=@ sgn=@])]
41 |%
42 ...
43```
44`+crub` cores (because they follow the `+acru` interface) are typically created using one of the constructors in [`+nu:crub`](#nu).
46### `+seal:as`
48```hoon
49 ++ seal ::
50 |= [bpk=pass msg=@]
51 ...
52```
54Forms a symmetric key using Diffie-Hellman key exchange with the secret key
55stored at `sgn.u.sek` and a public key `bpk`. Then `+sign`s `msg`, encrypts the
56signed message using `+en:siva:aes` with the symmetric key, and then `+jam`s it.
58Crashes if `sek` is null.
60### `+sign:as` {#sign-as}
62```hoon
63 ++ sign ::
64 |= msg=@
65 ...
66```
68Signs message `msg=@` using the secret authentication key `sgn.u.sek`, then forms a
69cell `[signed-message msg]` and `+jam`s it.
71Crashes if `sek` is null.
73### `+sure:as`
75```hoon
76 ++ sure ::
77 |= txt=@
78 ...
79```
81`+cue`s `txt` to get a signature `sig=@` and message `msg=@`. Verifies that
82`sig` was `msg` signed using the secret key associated to the public key stored
83at `sgn.pub`. Returns `(unit msg)` if so, null otherwise.
85### `+tear:as`
87```hoon
88 ++ tear ::
89 |= [bpk=pass txt=@]
90 ...
91```
93Forms a secret symmetric key using Diffie-Hellman key exchange using the secret
94key `cry.u.sek` and encryption key part of the public key `bpk` (which here is a
95concatenation of both the encryption and authentication public keys). `+cue`s
96`txt` and decrypts it using `+de:siva:aes` with the symmetric key. If decryption
97is successful, verifies the decrypted message using authentication key part of
98`bpk`, and returns it if so. Returns null otherwise.
100Crashes if `sek` is null.
102### `+de`
104```hoon
105 ++ de :: decrypt
106 |= [key=@J txt=@]
107 ...
108```
110`+cue`s `txt` then decrypts with the symmetric key `key` using `+de:sivc:aes`.
111Returns null in case of failure.
113### `+dy`
115```hoon
116 ++ dy :: need decrypt
117 |= [key=@J cph=@]
118 ...
119```
121Same as `+dy`, but crashes in case of failure.
123### `+en` {#en}
125```hoon
126 ++ en :: encrypt
127 |= [key=@J msg=@]
128```
130Encrypts `msg` with the symmetric key `key` using `en:sivc:aes`, then `+jam`s
131it.
133### `+fig:ex`
135Returns the fingerprint (SHA-256) of `+pub:ex`.
137### `+pac:ex`
139Returns the fingerprint (SHA-256) of `+sec:ex`. Crashes if `sek` is null.
141### `+pub:ex`
143Returns the concatenation of `sgn.pub` and `cry.pub`.
145### `+sec:ex`
147Returns the concatenation of `sgn.u.sek` and `cry.u.sek`.
149### `+pit:nu` {#nu}
151```hoon
152 ++ pit :: create keypair
153 |= [w=@ seed=@]
154 ...
155```
157Creates a `+crub` core with encryption and authentication public/private keypairs
158generated from a bitwidth `w` and `seed`. The private keys are generated with
159SHA-512, while `+puck:ed:crypto` is used to derive the public keys from the
160private keys.
162This is how one typically generates a brand new `+crub` core for signing and
163encrypting your own messages.
165### `+nol:nu`
167```hoon
168 ++ nol :: activate secret
169 |= a=ring
170 ...
171```
173Takes in a `ring` from a `+sec:ex:crub` and generates a new `+crub` core with
174`sek` taken from `+sec:ex` and `pub` generated with `+puck:ed:crypto`. Crashes
175if `+sec:ex` is not a `+crub` secret key.
177### `+com:nu`
179```hoon
180 ++ com :: activate public
181 |= a=pass
182 ...
183```
185Takes in a `pass` from a `+pub:ex:crub` and generates a new `+crub` core with
186`pub` taken from `+pub:ex` and null `sek`.
188## `+ed:crypto` {#ed}
190This core contains cryptographic primitives and helper functions for elliptic
191curve cryptography with [Curve25519](https://en.wikipedia.org/wiki/Curve25519).
193`+ed:crypto` is primarily used to generate public/private keypairs from a seed
194for use with [elliptic curve
195Diffie-Hellman](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman)
196key agreements as well as [Elliptic Curve Digital Signature
197Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm).
198These functionalities are ultimately utilized by [`+crub:crypto`](#crub), the
199only cryptosuite which [Ames](@/docs/arvo/ames/ames.md) makes use of.
201Most gates in `+ed:crypto` are [jetted](@/docs/vere/jetting.md), meaning that an
202external reference library is utilized whenever these functions are called,
203rather than running in Nock natively. See the [Vere
204documentation](@/docs/vere/cryptography.md#ed) for more information about the
205library utilized by jets.
207## `+aes:crypto` {#aes}
209This core contains cryptographic primitives and helper functions for
210[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) symmetric key
211encryption and decryption. As is the case with `ed:crypto`, these
212functionalities are utilized by [`+crub:crypto`](#crub), and most gates are
213jetted. See also the Vere documentation on [AES
214SIV](@/docs/vere/cryptography.md#aes) for more information about the library
215utilized by jets.
217This core contains several doors, each one used for a different variation of AES
218according to key size and mode. The only ones currently in use are
219`+siva:aes:crypto` and `+sivc:aes:crypto`, which are 128-bit and
220256-bit modes of [`AES-SIV`](https://www.aes-siv.com) respectively.