Guide

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.

createCrypto

createCrypto(sodium: Sodium): Crypto

Returns every function below, bound to the libsodium you pass. Call it after await sodium.ready.

Spec

createUserKeys

createUserKeys(): KeyPair

A user's X25519 key pair (crypto_box_keypair). privateKey is key_A.

Spec

newGroupKey

newGroupKey(): Uint8Array

A random 32-byte key for one group's rows.

Spec

newSalt

newSalt(): Uint8Array

A random 16-byte salt for passwordKeys, stored next to the wrap.

Spec

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), cannot hash password (Argon2id failed, for example out of memory).

Spec

newRecoveryWords

newRecoveryWords(): string

12 English BIP-39 words carrying 128 random bits. Show them once.

Spec

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: invalid recovery words (an unknown word, a bad checksum or a word count BIP-39 doesn't allow), without quoting what was typed. A valid phrase of more than 12 words gives recovery entropy must be 16 bytes.

Spec

keyFromPrf

keyFromPrf(prf: Uint8Array): Uint8Array

key_F from a passkey's 32-byte PRF output.

Throws: prf must be 32 bytes.

Spec

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).

Spec

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.

Spec

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.

Spec

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.

Spec

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, invalid public key (a key libsodium refuses, such as 32 zero bytes).

Spec

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.

Spec

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, invalid public key.

Spec

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.

Spec

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.

Spec

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, invalid public key (the link public key from the QR code).

Spec

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.

Spec

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.

MessageMeans
ezpriv: cannot decryptWrong key, or the ciphertext was moved (other table, id, user or kind) or changed
ezpriv: cannot openSealed to another public key, or changed
ezpriv: wrong contextOpened with another group id, context, channel or user than it was sealed for
ezpriv: unsupported versionThe first byte isn't 0x01
ezpriv: ciphertext too shortTruncated input
ezpriv: <name> must be <n> bytesA key, salt or PRF output of the wrong length, or a valid recovery phrase of more than 12 words
ezpriv: password params …Argon2id parameters that aren't integers, or are outside the floor and cap
ezpriv: invalid public keySealing to a public key libsodium refuses, such as 32 zero bytes
ezpriv: cannot hash passwordArgon2id failed, for example when it can't allocate its memory
ezpriv: invalid recovery wordsAn unknown word, a bad checksum or a word count BIP-39 doesn't allow
ezpriv: linked keys don't matchopenLink got a private key that doesn't belong to the public key