Crypto Functions¶
Holochain DNA instances are designed to function in the context of a Distributed Public Key Insfrastructure (DPKI) which:
- manages key creation and revocation
- manages an agency context that allows grouping and verifying that sets of DNA instances are controlled by the same agent.
- creates a context for identity verification
Holochain assumes that there may be different DPKI implementations but provides a reference implementation we call DeepKey. We assume that the DPKI implementation is itself a Holochain application, and we provide access to a set of generic cryptographic functions. These functions also allow DNA authors to build ad-hoc cryptogrpahic protocols.
For each Holochain DNA instance, the conductor maintains a Keystore, which holds “secrets” (seeds and keys) needed for cryptographic signing and encrypting. Each of the secrets in the Keystore is associated with a string which is a handle needed when using that secret for some cryptographic operation. Our cryptographic implementation is based on libsodium, and the seeds use their notions of context and index for key derivation paths. This implementation allows DNA developers to securely call cryptographic functions from wasm which will be executed in the conductor’s secure memory space when actually doing the cryptographic processing.
Here are the available functions:
keystore_list()
-> returns a list of all the secret identifiers in the keystorekeystore_new_random(dst_id)
-> creates a new random root seed identified bydst_id
keystore_derive_seed(src_id,dst_id,context,index)
-> derives a higherarchical deterministic key seed to be identifided bydst_id
from thesrc_id
. Usescontext
andindex
as part of the derivation path.keystore_derive_key(src_id,dst_id,key_type)
-> derives a key (signing or encrypting) to be identified bydst_id
from a previously created seed identified bysrc_id
. This function returns the public key of the keypair.keystore_sign(src_id,payload)
-> returns a signature of the payload as signed by the key identified bysrc_id
keystore_get_public_key(src_id)
-> returns a the public key of a key identified bysrc_id
. Returns an error if you pass an identifier of a seed secret.sign(payload)
-> signs the payload using the DNA’s instance agent ID public key. This is a convenience function which is equivalent to callingkeystore_sign("primary_keybundle:sign_key",payload)
sign_one_time(payload_list)
-> signs the payloads with a randomly generated key-pair, returning the signatures and the public key of the key-pair after shredding the private-key.verify_signature(provenance, payload)
-> verifies that thepayload
matches theprovenance
which is a public key/signature pair.encrypt(payload)
-> encrypts a message with theagent
private key.decrypt(payload)
-> decrypts a message with theagent
private key
Not Yet Implemented:
keystore_encrypt(src_id,payload)