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

git.iko.soy/urbit.org

on master help sign in

edits and clarifications

69fd27ddrbeefsupreme5 years ago

arvo/ames/cryptography.md+32−26

compare with master

unifiedsplit

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

2title = "Cryptography"

3weight = 5

4template = "doc.html"

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

6+++

5+++

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

27## Packet encryption and authentication {#packets}

26## Packet encryption and authentication {#packets}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

51[Diffie-Hellman key

50[Diffie-Hellman key

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

51exchange](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.

55## Comet self-attestation {#comets}

57## Comet self-attestation {#comets}

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

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

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

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

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

61its 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

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

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

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

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

64+is generated with

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

66+`sys/zuse.hoon`.

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

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

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

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

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

107

111

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

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

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

113may 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

111how the specific cryptosuite utilized by Ames is implemented.

116how the specific cryptosuite utilized by Ames is implemented.

112

117

113#### `+as:acru`

118#### `+as:acru`

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

128

133

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

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

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

135construct 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

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

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

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

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

134only the public key.

139only the public key.

135

140

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

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

137

142

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

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

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

145+and `+dy` crashes upon failure.

140

146

arvo/reference/cryptography.md+64−57

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

5+++

7This 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.

10## Summary

17## Summary

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

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

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

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

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

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

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

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

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}

48`+crub:crypto` implements an

26`+crub:crypto` implements an

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

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

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

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

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)

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

31implemented 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),

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

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

56`+ed:crypto`.

34`+ed:crypto`.

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

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

59−optional secret encryption and authentication keys.

37+keys and optional secret encryption and authentication keys.

60```hoon

38```hoon

61 ++ crub !:

39 ++ crub !:

62 ^- acru

40 ^- acru

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

64 |%

42 |%

65 ...

43 ...

66```

44```

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).

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

47+### `+seal:as`

72```hoon

49```hoon

73 ++ seal ::

50 ++ seal ::

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

82Crashes if `sek` is null.

59Crashes if `sek` is null.

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

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

86```hoon

63```hoon

87 ++ sign ::

64 ++ sign ::

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

95Crashes if `sek` is null.

72Crashes if `sek` is null.

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

74+### `+sure:as`

99```hoon

76```hoon

100 ++ sure ::

77 ++ sure ::

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

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

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

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

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

108

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

86+### `+tear:as`

110

111```hoon

88```hoon

112 ++ tear ::

89 ++ tear ::

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

123

100

124Crashes if `sek` is null.

101Crashes if `sek` is null.

125

102

126−#### `+de`

103+### `+de`

127

104

128```hoon

105```hoon

129 ++ de :: decrypt

106 ++ de :: decrypt

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

131 ...

108 ...

132```

109```

133

110

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`.

135Returns null in case of failure.

112Returns null in case of failure.

136

113

137−#### `+dy`

114+### `+dy`

138

115

139```hoon

116```hoon

140 ++ dy :: need decrypt

117 ++ dy :: need decrypt

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

144

121

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

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

146

123

147−#### `+en`

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

148

125

149```hoon

126```hoon

150 ++ en :: encrypt

127 ++ en :: encrypt

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

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

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

155it.

132it.

156

133

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

134+### `+fig:ex`

158

135

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

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

160

137

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

138+### `+pac:ex`

162

139

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

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

164

141

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

142+### `+pub:ex`

166

143

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

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

168

145

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

146+### `+sec:ex`

170

147

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

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

172

149

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

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

174

151

175```hoon

152```hoon

176 ++ pit :: create keypair

153 ++ pit :: create keypair

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

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

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

187encrypting your own messages.

164encrypting your own messages.

188

165

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

166+### `+nol:nu`

190

167

191```hoon

168```hoon

192 ++ nol :: activate secret

169 ++ nol :: activate secret

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

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

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

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

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

200

177

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

178+### `+com:nu`

202

179

203```hoon

180```hoon

204 ++ com :: activate public

181 ++ com :: activate public

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

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

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

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

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

211

188

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+

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

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.

213

217

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.

215

222

vere/cryptography.md+2−3

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

2title = "Cryptography"

3weight = 6

4template = "doc.html"

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

6+++

5+++

8All cryptographic primitives utilized by Arvo are

7All cryptographic primitives utilized by Arvo are

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

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

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

27`/dev/urandom` on nix).

26`/dev/urandom` on nix).

29−### AES SIV {#aes}

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

31−The library we utilize for AES SIV is an

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

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

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

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

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

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

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