# Module hdk::x_salsa20_poly1305

source · ## Expand description

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.

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

- Generate a new x25519 keypair in lair from entropy. Only the pubkey is returned from lair because the secret key never leaves lair.
- Libsodium keypair based authenticated encryption: box_open
- Libsodium keypair based authenticated encryption: box.
- Libsodium secret-key authenticated encryption: secretbox_open
- Libsodium secret-key authenticated encryption: secretbox.
- 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. - Using the Libsodium box algorithm, encrypt a shared secret so that it may be forwarded to another specific peer.
- 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.