69fd27d · urbit.org · git.iko.soy

git.iko.soy/urbit.org

edits and clarifications

commit69fd27d1e0018c9b2c9e4b0edec40714ff4052d7 authordrbeefsupreme <drbeefsupreme@discordja.net> dateWed 9 Jun 2021, 11:59 (5 years ago) parent576ee72

3 files changed+98−86

compare with master

unifiedsplit

arvo/ames/cryptography.md+32−26 arvo/reference/cryptography.md+64−57 vere/cryptography.md+2−3

arvo/ames/cryptography.md+32−26

@@ -2,7 +2,6 @@

22title = "Cryptography"

33weight = 5

44template = "doc.html"

5−aliases = ["/docs/learn/arvo/ames/"]

65+++

87Here we give a technical overview of how Ames implements cryptography.

@@ -19,16 +18,16 @@ this are comet [self-attestation packets](#comets), which are unencrypted.

1918All packets are also [signed](#packets) using [Elliptic Curve Digital Signature

2019Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm).

2120

22−The `$ames-state` includes a [`+acru:ames`](#crypto-core) core, an interface core

23−into which one of the cryptosuites in `zuse` may be implemented. Some, but not

24−all, of the cryptography-related tasks (encryption, signing, decrypting, and

25−authenticating) are peformed utilizing the `+acru` core.

21+The `$ames-state` includes a [`+acru:ames`](#crypto-core) core, an interface

22+core into which one of the cryptosuites in `zuse` may be implemented. Some, but

23+not all, of the calls to cryptography-related tasks (encryption, signing,

24+decrypting, and authenticating) are peformed utilizing the `+acru` core.

2625

2726## Packet encryption and authentication {#packets}

2827

29−Each Urbit ship possesses two networking keypairs: one for encryption, and one for

30−authentication. We often refer to these two keypairs as though they were a single keypair,

31−because they are stored as a single atom. [Elliptic Curve

28+Each Urbit ship possesses two networking keypairs: one for encryption, and one

29+for authentication. We often refer to these two keypairs as though they were a

30+single keypair because they are stored as a single atom. [Elliptic Curve

3231Diffie-Hellman](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman)

3332is used for encryption, while [Elliptic Curve Digital Signature

3433Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm)

@@ -37,29 +36,34 @@ is used for authentication

3736The encrypted payload of each packet is a `$shut-packet`, which is the `+jam` of

3837a cell with the `bone`, message number, and message fragment or ack (see

3938[Ames](@/docs/ames/ames.md) for more information on packet structure). The

40−message fragment is signed using the authentication key. It is

41−encrypted using `+sivc:aes:crypto` found in `sys/zuse.hoon`, which is an arm

42−utilized for 256-bit AES SIV symmetric encryption.

39+message fragment is signed using the authentication key. It is encrypted using

40+[`+en:crub:crypto`](@/docs/arvo/reference/cryptography.md#en) found in

41+`sys/zuse.hoon`, which utilizes the 256-bit AES-SIV algorithm.

4342

4443## Diffie-Hellman key exchange {#key-exchange}

4544

46−For each foreign ship a given ship has met, `$ames-state` contains a `$peer-state`,

47−inside which the `$symmetric-key` (an atom which nests under `@uw`) is utilized

48−for encrypting all Ames packets shared between the two ships. The

49−`symmetric-key` is derived using `+shar:ed:crypto` found in `sys/zuse.hoon`,

45+For each foreign ship a given ship has met, `$ames-state` contains a

46+`$peer-state`, inside which the `$symmetric-key` (an atom which nests under

47+`@uw`) is utilized for encrypting all Ames packets shared between the two ships.

48+The `symmetric-key` is derived using [`+shar:ed:crypto`](@/docs/arvo/reference/cryptography.md#shar) found in `sys/zuse.hoon`,

5049which is an arm utilized for generating the symmetric key for elliptic curve

5150[Diffie-Hellman key

5251exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange)

53−with [curve25519](https://en.wikipedia.org/wiki/Curve25519).

52+with [curve25519](https://en.wikipedia.org/wiki/Curve25519). Briefly, each ship

53+in a two-way conversation computes the shared symmetric key for that

54+conversation by computing the product of their own private key and the public

55+key of the other party.

5456

5557## Comet self-attestation {#comets}

5658

57−Recall that the `@p` of a comet is the hash of their 128-bit public key cast as a

58−`@p`. Since the public key of a comet is not stored on Azimuth, a comet proves

59+Recall that the `@p` of a comet is the hash of their 128-bit public key cast as

60+a `@p`. Since the public key of a comet is not stored on Azimuth, a comet proves

5961its identity with an "attestation packet". This is an unencrypted packet whose

60−payload is the comet's signature created with its private key. This is the

61−only situation in which a ship will send an unencrypted packet. The signature is

62−generated with `+sign:as:crub` found in `sys/zuse.hoon`.

62+payload is the comet's signature created with its private key. This is the only

63+circumstance under which a ship will send an unencrypted packet. The signature

64+is generated with

65+[`+sign:as:crub`](@/docs/arvo/reference/cryptography.md#sign-as) found in

66+`sys/zuse.hoon`.

6367

6468Upon hearing an attestation packet, the receiving ship will generate a symmetric

6569key for communications with the comet, according to the [key

@@ -107,7 +111,8 @@ Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).

107111

108112As the `+acru` core is merely an interface, the details on how it is utilized

109113may vary according to the cryptosuite implemented in it. We summarize what each

110−core is utilized for here, but see [`crub:crypto`](#crub) for more details on

114+core is utilized for here, but see

115+[`crub:crypto`](@/docs/arvo/reference/cryptography.md#crub) for more details on

111116how the specific cryptosuite utilized by Ames is implemented.

112117

113118#### `+as:acru`

@@ -128,13 +133,14 @@ returned as a single atom.

128133

129134This core contains constructors for the `+acru` core. `+pit:nu` is used to

130135construct an `+acru` core with both a private and public key (i.e. both

131−`+sec:ex` and `pub:ex` are set) from a bitlength and seed. `+nol:nu` can then be

136+`+sec:ex` and `+pub:ex` are set) from a bitlength and seed. `+nol:nu` can then be

132137called from an `+acru` core created with `+pit:nu` to get an `+acru` core with

133138only the secret key, while `+com:nu` can be called to get an `+acru` core with

134139only the public key.

135140

136−#### `+de`, `+dy`, `+en`

141+#### `+en:acru`, `+de:acru`, and `+dy:acru`

137142

138−These arms are for symmetric encryption and decryption. In case of failure,

139−`+de` returns null and `+dy` crashes.

143+These arms are for symmetric encryption (`+en`) and decryption (`+de` and

144+`+dy`). The difference between the decryption arms is that `+de` returns null

145+and `+dy` crashes upon failure.

140146

arvo/reference/cryptography.md+64−57

@@ -5,58 +5,36 @@ template = "doc.html"

55+++

77This is a summary of the cryptography functions found in `sys/zuse.hoon`, Arvo's

8−standard library.

8+standard library. This page currently only documents cryptographic functions

9+directly utilized by [Ames](@/docs/arvo/ames/ames.md). `zuse` also contains

10+cryptographic functions relevant to Ethereum such as the `+keccak:crypto` core,

11+but they are currently undocumented.

12+

13+Documentation for [Insecure Hashing](@/docs/hoon/reference/stdlib/2e.md) and the

14+[SHA Hash Family](@/docs/reference/stdlib/3d.md) is found in the Hoon standard

15+library reference.

916

1017## Summary

1118

12−`zuse` contains several cryptosuites. The only ones currently in use are

13−`+ed:crypto`, `+aes:crypto`, and `+crub:crypto`, with the latter being the

14−only one which is implementable as an [`+acru:ames`

19+`zuse` contains several cryptosuites. The ones utilized by Ames are

20+[`+ed:crypto`](#ed), [`+aes:crypto`](#aes), and [`+crub:crypto`](#crub), with

21+the latter being the only one which is implementable as an [`+acru:ames`

1522core](@/docs/arvo/ames/cryptography/#crypto-core).

1623

17−### `+ed:crypto` {#ed}

18−

19−This core contains cryptographic primitives and helper functions for elliptic

20−curve cryptography with [Curve25519](https://en.wikipedia.org/wiki/Curve25519).

21−

22−`+ed:crypto` is used to generate public/private keypairs from a seed for use

23−with [elliptic curve

24−Diffie-Hellman](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman)

25−key agreements as well as [Elliptic Curve Digital Signature

26−Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm).

27−These functionalities are ultimately utilized by [`+crub:crypto`](#crub), the

28−only cryptosuite which [Ames](@/docs/arvo/ames/ames.md) makes use of.

29−

30−Most gates in `+ed:crypto` are [jetted](@/docs/vere/jetting.md), meaning that an

31−external reference library is utilized whenever these functions are called,

32−rather than running in Nock natively. See the [Vere

33−documentation](@/docs/vere/cryptography/#ed) for more information about the

34−library utilized by jets.

35−

36−### `+aes:crypto` {#aes}

37−

38−This core contains cryptographic primitives and helper functions for

39−[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) symmetric key

40−encryption and decryption. As is the case with `ed:crypto`, these

41−functionalities are utilized by [`+crub:crypto`](#crub), and most functions are

42−jetted. See also the Vere documentation on [AES

43−SIV](@/docs/vere/cryptography/#aes) for more information about the library

44−utilized by jets.

45−

46−### `+crub:crypto` {#crub}

24+## `+crub:crypto` {#crub}

4725

4826`+crub:crypto` implements an

4927[`+acru:ames`](@/docs/arvo/ames/cryptography/#crypto-core) core that implements

5028[Suite B Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).

5129

52−It utilizes AES symmetric key encryption and decryption from `+aes:crypto`

30+It utilizes AES symmetric key encryption and decryption from [`+aes:crypto`](#aes)

5331implemented using the Diffie-Hellman key exchange protocol, elliptic curve

54−digital signature algorithm (ECDSA) signing and verification with `+ed:crypto`,

32+digital signature algorithm (ECDSA) signing and verification with [`+ed:crypto`](#ed),

5533and generates public/private key pairs using elliptic curve cryptography with

5634`+ed:crypto`.

5735

58−`+crub:crypto` is called with public encryption and authentication keys and

59−optional secret encryption and authentication keys.

36+A `+crub:crypto` core's payload contains public encryption and authentication

37+keys and optional secret encryption and authentication keys.

6038```hoon

6139 ++ crub !:

6240 ^- acru

@@ -64,10 +42,9 @@ optional secret encryption and authentication keys.

6442 |%

6543 ...

6644```

67−`+crub` cores are typically not created by directly calling the gate, but

68−instead using one of the constructors in `+nu:crub`.

45+`+crub` cores are typically created using one of the constructors in [`+nu:crub`](#nu).

6946

70−#### `+seal:as`

47+### `+seal:as`

7148

7249```hoon

7350 ++ seal ::

@@ -81,7 +58,7 @@ signed message using `+en:siva:aes` with the symmetric key, and then `+jam`s it.

8158

8259Crashes if `sek` is null.

8360

84−#### `+sign:as`

61+### `+sign:as` {#sign:as}

8562

8663```hoon

8764 ++ sign ::

@@ -94,7 +71,7 @@ cell `[signed-message msg]` and `+jam`s it.

9471

9572Crashes if `sek` is null.

9673

97−#### `+sure:as`

74+### `+sure:as`

9875

9976```hoon

10077 ++ sure ::

@@ -106,7 +83,7 @@ Crashes if `sek` is null.

10683`sig` was `msg` signed using the secret key associated to the public key stored

10784at `sgn.pub`. Returns `(unit msg)` if so, null otherwise.

10885

109−#### `+tear:as`

86+### `+tear:as`

11087

11188```hoon

11289 ++ tear ::

@@ -123,7 +100,7 @@ is successful, verifies the decrypted message using authentication key part of

123100

124101Crashes if `sek` is null.

125102

126−#### `+de`

103+### `+de`

127104

128105```hoon

129106 ++ de :: decrypt

@@ -131,10 +108,10 @@ Crashes if `sek` is null.

131108 ...

132109```

133110

134−`+cue`s `txt` then decrypts with the symmetric key `key` using `de:sivc:aes`.

111+`+cue`s `txt` then decrypts with the symmetric key `key` using `+de:sivc:aes`.

135112Returns null in case of failure.

136113

137−#### `+dy`

114+### `+dy`

138115

139116```hoon

140117 ++ dy :: need decrypt

@@ -144,7 +121,7 @@ Returns null in case of failure.

144121

145122Same as `+dy`, but crashes in case of failure.

146123

147−#### `+en`

124+### `+en` {#en}

148125

149126```hoon

150127 ++ en :: encrypt

@@ -154,23 +131,23 @@ Same as `+dy`, but crashes in case of failure.

154131Encrypts `msg` with the symmetric key `key` using `en:sivc:aes`, then `+jam`s

155132it.

156133

157−#### `+fig:ex`

134+### `+fig:ex`

158135

159136Returns the fingerprint (SHA-256) of `+pub:ex`.

160137

161−#### `+pac:ex`

138+### `+pac:ex`

162139

163140Returns the fingerprint (SHA-256) of `+sec:ex`. Crashes if `sek` is null.

164141

165−#### `+pub:ex`

142+### `+pub:ex`

166143

167144Returns the concatenation of `sgn.pub` and `cry.pub`.

168145

169−#### `+sec:ex`

146+### `+sec:ex`

170147

171148Returns the concatenation of `sgn.u.sek` and `cry.u.sek`.

172149

173−#### `+pit:nu`

150+### `+pit:nu` {#nu}

174151

175152```hoon

176153 ++ pit :: create keypair

@@ -186,7 +163,7 @@ private keys.

186163This is how one typically generates a brand new `+crub` core for signing and

187164encrypting your own messages.

188165

189−#### `+nol:nu`

166+### `+nol:nu`

190167

191168```hoon

192169 ++ nol :: activate secret

@@ -198,7 +175,7 @@ Takes in a `ring` from a `+sec:ex:crub` and generates a new `+crub` core with

198175`sek` taken from `+sec:ex` and `pub` generated with `+puck:ed:crypto`. Crashes

199176if `+sec:ex` is not a `+crub` secret key.

200177

201−#### `+com:nu`

178+### `+com:nu`

202179

203180```hoon

204181 ++ com :: activate public

@@ -209,7 +186,37 @@ if `+sec:ex` is not a `+crub` secret key.

209186Takes in a `pass` from a `+pub:ex:crub` and generates a new `+crub` core with

210187`pub` taken from `+pub:ex` and null `sek`.

211188

212−### `+secp:crypto` {#secp}

189+## `+ed:crypto` {#ed}

190+

191+This core contains cryptographic primitives and helper functions for elliptic

192+curve cryptography with [Curve25519](https://en.wikipedia.org/wiki/Curve25519).

193+

194+`+ed:crypto` is primarily used to generate public/private keypairs from a seed

195+for use with [elliptic curve

196+Diffie-Hellman](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman)

197+key agreements as well as [Elliptic Curve Digital Signature

198+Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm).

199+These functionalities are ultimately utilized by [`+crub:crypto`](#crub), the

200+only cryptosuite which [Ames](@/docs/arvo/ames/ames.md) makes use of.

201+

202+Most gates in `+ed:crypto` are [jetted](@/docs/vere/jetting.md), meaning that an

203+external reference library is utilized whenever these functions are called,

204+rather than running in Nock natively. See the [Vere

205+documentation](@/docs/vere/cryptography/#ed) for more information about the

206+library utilized by jets.

207+

208+## `+aes:crypto` {#aes}

209+

210+This core contains cryptographic primitives and helper functions for

211+[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) symmetric key

212+encryption and decryption. As is the case with `ed:crypto`, these

213+functionalities are utilized by [`+crub:crypto`](#crub), and most gates are

214+jetted. See also the Vere documentation on [AES

215+SIV](@/docs/vere/cryptography/#aes) for more information about the library

216+utilized by jets.

213217

214−Utilized for secp256k1 (Ethereum public and private keys).

218+This core contains several doors, each one used for a different variation of AES

219+according to key size and mode. The only ones currently in use are

220+`+siva:aes:crypto` and `+sivc:aes:crypto`, which are 128-bit and

221+256-bit modes of [`AES-SIV`](https://www.aes-siv.com) respectively.

215222

vere/cryptography.md+2−3

@@ -2,7 +2,6 @@

22title = "Cryptography"

33weight = 6

44template = "doc.html"

5−aliases = ["/docs/learn/vere/jetting/"]

65+++

87All cryptographic primitives utilized by Arvo are

@@ -26,9 +25,9 @@ All code is pure ANSI C without any dependencies, except for the random seed

2625generation which uses standard OS cryptography APIs (CryptGenRandom on Windows,

2726`/dev/urandom` on nix).

2827

29−### AES SIV {#aes}

28+### AES-SIV {#aes}

3029

31−The library we utilize for AES SIV is an

30+The library we utilize for AES-SIV is an

3231[RFC5297](https://tools.ietf.org/html/rfc5297)-compliant C implementation of

3332AES-SIV written by Daniel Franke on behalf of [Akamai

3433Technologies](https://www.akamai.com). It is published under the [Apache License