mirror of
https://github.com/urbit/shrub.git
synced 2024-12-22 10:21:31 +03:00
52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
What is urcrypt?
|
|
----------------
|
|
urcrypt is a library of cryptography routines used by urbit jets.
|
|
|
|
Why is urcrypt?
|
|
---------------
|
|
Urbit's C runtime (long the only urbit runtime) has accumulated a collection of
|
|
cryptography dependencies, some with custom additions or patches. These
|
|
libraries have different conventions and have been managed by u3 in an ad-hoc
|
|
manner. Reproducing that arrangement in other runtimes is tricky and
|
|
error-prone. The (sometimes inconsistent) logic must be reproduced and suitable
|
|
cryptography primitives must be found (or worse, written) for the new
|
|
environment.
|
|
|
|
To ease these burdens, urcrypt isolates the quirks behind a consistent calling
|
|
convention. Everything is a little-endian byte array, and each jetted operation
|
|
has a corresponding function in the library. Jets simply unpack their nouns,
|
|
call urcrypt, and pack the results.
|
|
|
|
What is a cryptography routine?
|
|
-------------------------------
|
|
This is more of a subjective question than it might appear. Any of the following
|
|
conditions are sufficient, but not necessary, for a function to be included in
|
|
urcrypt:
|
|
|
|
* The routine is sensitive to side-channel attacks (encryption, etc)
|
|
* Some property of the routine is cryptographically useful (SHA, RIPE, etc)
|
|
* The routine typically lives in a crypto library, for whatever reason.
|
|
|
|
Shared or static?
|
|
-----------------
|
|
Urcrypt has a number of dependencies, and there is something of a matrix of
|
|
combinations of static and shared versions of those dependencies. To keep things
|
|
simple, two modes are currently supported:
|
|
|
|
* A static library archive (urcrypt.a)
|
|
* A shared object with internal, statically linked dependencies
|
|
(urcrypt.{so, dll, dylib, etc})
|
|
|
|
pkg-config can be used in the normal way to obtain the link parameters.
|
|
|
|
A word on OpenSSL
|
|
-----------------
|
|
Urcrypt depends on OpenSSL's libcrypto, which has custom malloc functions.
|
|
Urcrypt tries to avoid dealing with global/static state, and mostly succeeds,
|
|
but users who need to control memory management will want to use
|
|
`CRYPTO_set_mem_functions` from OpenSSL. This is no problem for a statically
|
|
linked urcrypt, but the shared object doesn't expose that symbol to users.
|
|
`urcrypt_set_openssl_mem_functions` is a trivial wrapper that is exposed,
|
|
and can be used to configure shared urcrypt's internal libcrypto malloc.
|
|
The function always fails in statically linked urcrypt.
|