secret

Creates a key shared between two pairs, so data can be encrypted for someone else. Both sides can create the same key: each uses the other's public epub key and their own private epriv key.

Parameter

Description

to

A pair object with the other person's epub key. The other keys aren't needed.

from

Your own pair object, with both epub and epriv keys, such as user.is.

callback

Optional function that receives the key. Leave it out to await it.

Returns a pair object containing only an epriv key, ready to pass to encrypt() and decrypt(). Returns null if either pair is missing a key.

Examples

const alice = await holster.SEA.pair()
const bob = await holster.SEA.pair()

// Alice creates a secret for Bob and encrypts a message with it.
const to = await holster.SEA.secret({epub: bob.epub}, alice)
const enc = await holster.SEA.encrypt("shared data", to)

// Bob creates the same secret and reads the message.
const from = await holster.SEA.secret({epub: alice.epub}, bob)
const dec = await holster.SEA.decrypt(enc, from)
console.log(dec) // "shared data"

// With a callback.
holster.SEA.secret({epub: bob.epub}, alice, to => console.log(to.epriv))

With user accounts

Every account's epub is stored publicly with it, so you can encrypt data for any account you know the public key of:

// Alice, logged in, encrypts a message for Bob.
const bobEpub = await user.get([bobPublicKey, "epub"])
const to = await holster.SEA.secret({epub: bobEpub}, user.is)
await user.get("for-bob").put(await holster.SEA.encrypt("hi Bob", to))

// Bob, logged in, reads it from Alice's account.
const aliceEpub = await user.get([alicePublicKey, "epub"])
const from = await holster.SEA.secret({epub: aliceEpub}, user.is)
const enc = await user.get([alicePublicKey, "for-bob"])
console.log(await holster.SEA.decrypt(enc, from)) // "hi Bob"