Module hdk::x_salsa20_poly1305

Encryption and decryption using the (secret)box algorithms popularised by Libsodium.

Libsodium defines and implements two encryption functions secretbox and box. The former implements shared secret encryption and the latter does the same but with a DH key exchange to generate the shared secret. This has the effect of being able to encrypt data so that only the intended recipient can read it. This is also repudiable so both participants know the data must have been encrypted by the other (because they didn’t encrypt it themselves) but cannot prove this to anybody else (because they could have encrypted it themselves). If repudiability is not something you want, you need to use a different approach.

Note that the secrets are located within the secure lair keystore (@todo actually secretbox puts the secret in WASM, but this will be fixed soon) and never touch WASM memory. The WASM must provide either the public key for box or an opaque reference to the secret key so that lair can encrypt or decrypt as required.

@todo implement a way to export/send an encrypted shared secret for a peer from lair

Note that even though the elliptic curve is the same as is used by ed25519, the keypairs cannot be shared because the curve is mathematically translated in the signing vs. encryption algorithms. In theory the keypairs could also be translated to move between the two algorithms but Holochain doesn’t offer a way to do this (yet?). Create new keypairs for encryption and save the associated public key to your local source chain, and send it to peers you want to interact with.

Functions

create_x25519_keypair

Generate a new x25519 keypair in lair from entropy. Only the pubkey is returned from lair because the secret key never leaves lair.

x_25519_x_salsa20_poly1305_decrypt

Libsodium keypair based authenticated encryption: box_open

x_25519_x_salsa20_poly1305_encrypt

Libsodium keypair based authenticated encryption: box.

x_salsa20_poly1305_decrypt

Libsodium secret-key authenticated encryption: secretbox_open

x_salsa20_poly1305_encrypt

Libsodium secret-key authenticated encryption: secretbox.

x_salsa20_poly1305_shared_secret_create_random

Generate a new secure random shared secret suitable for encrypting and decrypting using x_salsa20_poly1305_{en,de}crypt. If key_ref is None an opaque reference will be auto-generated. If key_ref is Some and that key already exists in the store, this function will return an error. If Ok, this function will return the KeyRef by which the shared secret may be accessed.

x_salsa20_poly1305_shared_secret_export

Using the Libsodium box algorithm, encrypt a shared secret so that it may be forwarded to another specific peer.

x_salsa20_poly1305_shared_secret_ingest

Using the Libsodium box algorithm, decrypt a shared secret, storing it in the keystore so that it may be used in x_salsa20_poly1305_decrypt. This method may be co-opted to ingest shared secrets generated by other custom means. Just be careful, as WASM memory is not a very secure environment for cryptographic secrets. If key_ref is None an opaque reference string will be auto-generated. If key_ref is Some and that key already exists in the store, this function will return an error. If Ok, this function will return the KeyRef by which the shared secret may be accessed.