API reference
One entry point, createCrypto(sodium), returns every function. Each takes and returns Uint8Array, and a function with more than three inputs takes one object.
createCryptocreateUserKeysnewGroupKeynewSaltpasswordKeysnewRecoveryWordskeyFromWordskeyFromPrfwrapKeyunwrapKeyencryptRowdecryptRowsealGroupKeyopenGroupKeysealForUseropenSealednewLinkRequestsealForLinkopenLink- Constants and types
- Errors
createCrypto
createCrypto(sodium: Sodium): Crypto
Returns every function below, bound to the libsodium you pass. Call it after await sodium.ready.
createUserKeys
createUserKeys(): KeyPair
A user's X25519 key pair (crypto_box_keypair). privateKey is key_A.
newGroupKey
newGroupKey(): Uint8Array
A random 32-byte key for one group's rows.
newSalt
newSalt(): Uint8Array
A random 16-byte salt for passwordKeys, stored next to the wrap.
passwordKeys
passwordKeys({ password, salt, params? }): { keyP, authKey }
Argon2id over the NFC-normalized password, then two subkeys: keyP wraps key_A, authKey is sent at sign-in instead of the password. params defaults to DEFAULT_PASSWORD_PARAMS.
Throws: salt must be 16 bytes, password params must be integers, password params below the minimum (under 2 passes or 19 MiB), password params above the maximum (over 16 passes or 256 MiB).
newRecoveryWords
newRecoveryWords(): string
12 English BIP-39 words carrying 128 random bits. Show them once.
keyFromWords
keyFromWords(words: string): Uint8Array
key_R from the 12 words. Trims, lowercases and joins with single spaces first, so case and extra spaces don't matter.
Throws: an unknown word, a bad checksum or the wrong number of words.
keyFromPrf
keyFromPrf(prf: Uint8Array): Uint8Array
key_F from a passkey's 32-byte PRF output.
Throws: prf must be 32 bytes.
wrapKey
wrapKey({ key, wrappingKey, userId, kind }): Uint8Array
Encrypts a key (usually key_A) under one way to unlock it. Bound to userId and kind. A 32-byte key gives a 73-byte wrap.
Throws: key must be 32 bytes (the wrapping key).
unwrapKey
unwrapKey({ wrapped, wrappingKey, userId, kind }): Uint8Array
The inverse of wrapKey, with the same userId and kind.
Throws: cannot decrypt, unsupported version, ciphertext too short.
encryptRow
encryptRow({ value, groupKey, table, rowId }): Uint8Array
Encrypts one row's bytes, bound to its table and id. Adds 41 bytes (version, nonce, tag).
Throws: key must be 32 bytes.
decryptRow
decryptRow({ encrypted, groupKey, table, rowId }): Uint8Array
The inverse of encryptRow. A row moved to another table or id, or with any byte changed, is refused.
Throws: cannot decrypt, unsupported version, ciphertext too short.
sealGroupKey
sealGroupKey({ groupKey, groupId, publicKey }): Uint8Array
Seals a group key to one member's public key, bound to the group id.
Throws: groupKey must be 32 bytes, publicKey must be 32 bytes.
openGroupKey
openGroupKey({ sealed, groupId, keyPair }): Uint8Array
Opens a sealed group key with the member's key pair.
Throws: cannot open, wrong context (another group), unsupported version.
sealForUser
sealForUser({ value, context, publicKey }): Uint8Array
Seals a value to a user's public key: anyone (the server) can seal, only the user opens. context names what it is.
Throws: publicKey must be 32 bytes.
openSealed
openSealed({ sealed, context, keyPair }): Uint8Array
Opens a value sealed with sealForUser for the same context. Ported to Swift and Kotlin.
Throws: cannot open, wrong context, unsupported version.
newLinkRequest
newLinkRequest(): LinkRequest
A one-time key pair and a 32-byte secret for a new browser. Its QR code carries publicKey and secret; the private key never leaves the browser.
sealForLink
sealForLink({ userKeys, channelId, userId, linkPublicKey, linkSecret }): Uint8Array
On the phone: encrypts the user's key pair under the QR secret, then seals it to the browser's one-time public key. Ask the user to confirm first: whoever showed the QR code gets the private key.
Throws: privateKey must be 32 bytes, publicKey must be 32 bytes, key must be 32 bytes.
openLink
openLink({ sealed, channelId, userId, linkKeys }): KeyPair
In the browser: opens the user's key pair. Compare the returned publicKey with the account's before using the keys.
Throws: cannot open, cannot decrypt, wrong context, linked keys don't match.
Constants and types
import { createCrypto, frame, VERSION, DEFAULT_PASSWORD_PARAMS } from "@ezpriv/crypto";
import type { Crypto, KeyPair, LinkRequest, PasswordParams, Sodium } from "@ezpriv/crypto";
VERSION; // 1: first byte of every ciphertext and first field of every frame
DEFAULT_PASSWORD_PARAMS; // { opsLimit: 3, memLimit: 64 * 1024 * 1024 }
frame(["1", "ezpriv/row", "expense", "42"]); // "1:1,10:ezpriv/row,7:expense,2:42,"
interface KeyPair { publicKey: Uint8Array; privateKey: Uint8Array }
interface LinkRequest extends KeyPair { secret: Uint8Array }
interface PasswordParams { opsLimit: number; memLimit: number /* bytes */ }
Sodium lists the libsodium functions the package calls, and nothing else. libsodium-wrappers-sumo and react-native-libsodium both satisfy it.
Errors
Every error is a plain Error whose message starts with ezpriv:. libsodium's own errors are caught and replaced, so the messages are the same on every runtime. Two exceptions for now, whose messages don't start with ezpriv:: keyFromWords passes on the errors of @scure/bip39, which can quote the mistyped word, so keep them out of logs; and sealGroupKey, sealForUser and sealForLink pass on libsodium's own error for an invalid public key (such as 32 zero bytes).
| Message | Means |
|---|---|
ezpriv: cannot decrypt | Wrong key, or the ciphertext was moved (other table, id, user or kind) or changed |
ezpriv: cannot open | Sealed to another public key, or changed |
ezpriv: wrong context | Opened with another group id, context, channel or user than it was sealed for |
ezpriv: unsupported version | The first byte isn't 0x01 |
ezpriv: ciphertext too short | Truncated input |
ezpriv: <name> must be <n> bytes | A key, salt or PRF output of the wrong length |
ezpriv: password params … | Argon2id parameters that aren't integers, or are outside the floor and cap |
ezpriv: linked keys don't match | openLink got a private key that doesn't belong to the public key |