Cryptography • Documentation • urbit.org

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 +signs msg, encrypts the signed message using +en:siva:aes with the symmetric key, and then +jams 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 +jams it.

Crashes if sek is null.

`+sure:as`

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

+cues 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). +cues 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=@]
      ...

+cues 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 +jams 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.