# Cryptography

This is a summary of the cryptography functions found in `sys/zuse.hoon`

, Arvo's
standard library. This page currently only documents cryptographic functions
directly utilized by Ames. `zuse`

also contains
cryptographic functions relevant to Ethereum such as the `+keccak:crypto`

core,
but they are currently undocumented.

Documentation for Insecure Hashing and the SHA Hash Family is found in the Hoon standard library reference.

## Summary

`zuse`

contains several cryptosuites. The ones utilized by Ames are
`+ed:crypto`

, `+aes:crypto`

, and `+crub:crypto`

, with
the latter being the only one which is implemented as an `+acru:ames`

-shaped core.

`+crub:crypto`

`+crub:crypto`

implements an
`+acru:ames`

core that implements
Suite B Cryptography.

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

implemented using the Diffie-Hellman key exchange protocol, elliptic curve
digital signature algorithm (ECDSA) signing and verification with `+ed:crypto`

,
and generates public/private key pairs using elliptic curve cryptography with
`+ed:crypto`

.

A `+crub:crypto`

core's payload contains public encryption and authentication
keys and optional secret encryption and authentication keys.

```
++ crub !:
^- acru
=| [pub=[cry=@ sgn=@] sek=(unit [cry=@ sgn=@])]
|%
...
```

`+crub`

cores (because they follow the `+acru`

interface) are typically created using one of the constructors in `+nu:crub`

.

`+seal:as`

```
++ seal ::
|= [bpk=pass msg=@]
...
```

Forms a symmetric key using Diffie-Hellman key exchange with the secret key
stored at `sgn.u.sek`

and a public key `bpk`

. Then `+sign`

s `msg`

, encrypts the
signed message using `+en:siva:aes`

with the symmetric key, and then `+jam`

s it.

Crashes if `sek`

is null.

`+sign:as`

```
++ sign ::
|= msg=@
...
```

Signs message `msg=@`

using the secret authentication key `sgn.u.sek`

, then forms a
cell `[signed-message msg]`

and `+jam`

s it.

Crashes if `sek`

is null.

`+sure:as`

```
++ sure ::
|= txt=@
...
```

`+cue`

s `txt`

to get a signature `sig=@`

and message `msg=@`

. Verifies that
`sig`

was `msg`

signed using the secret key associated to the public key stored
at `sgn.pub`

. Returns `(unit msg)`

if so, null otherwise.

`+tear:as`

```
++ tear ::
|= [bpk=pass txt=@]
...
```

Forms a secret symmetric key using Diffie-Hellman key exchange using the secret
key `cry.u.sek`

and encryption key part of the public key `bpk`

(which here is a
concatenation of both the encryption and authentication public keys). `+cue`

s
`txt`

and decrypts it using `+de:siva:aes`

with the symmetric key. If decryption
is successful, verifies the decrypted message using authentication key part of
`bpk`

, and returns it if so. Returns null otherwise.

Crashes if `sek`

is null.

`+de`

```
++ de :: decrypt
|= [key=@J txt=@]
...
```

`+cue`

s `txt`

then decrypts with the symmetric key `key`

using `+de:sivc:aes`

.
Returns null in case of failure.

`+dy`

```
++ dy :: need decrypt
|= [key=@J cph=@]
...
```

Same as `+dy`

, but crashes in case of failure.

`+en`

```
++ en :: encrypt
|= [key=@J msg=@]
```

Encrypts `msg`

with the symmetric key `key`

using `en:sivc:aes`

, then `+jam`

s
it.

`+fig:ex`

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

.

`+pac:ex`

Returns the fingerprint (SHA-256) of `+sec:ex`

. Crashes if `sek`

is null.

`+pub:ex`

Returns the concatenation of `sgn.pub`

and `cry.pub`

.

`+sec:ex`

Returns the concatenation of `sgn.u.sek`

and `cry.u.sek`

.

`+pit:nu`

```
++ pit :: create keypair
|= [w=@ seed=@]
...
```

Creates a `+crub`

core with encryption and authentication public/private keypairs
generated from a bitwidth `w`

and `seed`

. The private keys are generated with
SHA-512, while `+puck:ed:crypto`

is used to derive the public keys from the
private keys.

This is how one typically generates a brand new `+crub`

core for signing and
encrypting your own messages.

`+nol:nu`

```
++ nol :: activate secret
|= a=ring
...
```

Takes in a `ring`

from a `+sec:ex:crub`

and generates a new `+crub`

core with
`sek`

taken from `+sec:ex`

and `pub`

generated with `+puck:ed:crypto`

. Crashes
if `+sec:ex`

is not a `+crub`

secret key.

`+com:nu`

```
++ com :: activate public
|= a=pass
...
```

Takes in a `pass`

from a `+pub:ex:crub`

and generates a new `+crub`

core with
`pub`

taken from `+pub:ex`

and null `sek`

.

`+ed:crypto`

This core contains cryptographic primitives and helper functions for elliptic curve cryptography with Curve25519.

`+ed:crypto`

is primarily used to generate public/private keypairs from a seed
for use with elliptic curve
Diffie-Hellman
key agreements as well as Elliptic Curve Digital Signature
Algorithm.
These functionalities are ultimately utilized by `+crub:crypto`

, the
only cryptosuite which Ames makes use of.

Most gates in `+ed:crypto`

are jetted, meaning that an
external reference library is utilized whenever these functions are called,
rather than running in Nock natively. See the Vere
documentation for more information about the
library utilized by jets.

`+aes:crypto`

This core contains cryptographic primitives and helper functions for
AES symmetric key
encryption and decryption. As is the case with `ed:crypto`

, these
functionalities are utilized by `+crub:crypto`

, and most gates are
jetted. See also the Vere documentation on AES
SIV for more information about the library
utilized by jets.

This core contains several doors, each one used for a different variation of AES
according to key size and mode. The only ones currently in use are
`+siva:aes:crypto`

and `+sivc:aes:crypto`

, which are 128-bit and
256-bit modes of `AES-SIV`

respectively.