Skip to content
Open app

ProtocolCryptography

Cryptography

How every key comes from one wallet signature, and how a message is sealed, opened and checked.

Every secret a wallet uses in Talaria comes from one signature over one fixed message. Nothing else needs to be stored for the keys to come back on another device. The SDK does all of this on the device, with @noble/curves (X25519), @noble/ciphers (XChaCha20-Poly1305) and @noble/hashes (HKDF, SHA-256, HMAC).

One content key, wrapped twice: once for the reader, once for the writer.

Keys#

The key derivation message#

The wallet signs this text, UTF-8 encoded, with its Ed25519 key. <address> is the wallet's base58 address. Lines end with a single line feed and there is no final newline.

key-derivation-message.txt
Talaria private inbox
Version: 1
Wallet: <address>
Sign to derive your inbox and local history keys. This does not send a transaction.

Signing it sends no transaction. Ed25519 signatures are deterministic, so the same wallet produces the same 64 bytes every time, on every device. The SDK exports the bytes as keyDerivationMessage(wallet).

Derivation#

Every key below is HKDF-SHA256 with the salt Talaria/v1, an info string, and 32 bytes of output:

Text
derive(key, info) = HKDF-SHA256(ikm = key, salt = "Talaria/v1", info = info, length = 32)
KeyDerived asUse
masterderive(signature, "wallet/<address>")The root of every key below. Never leaves the device.
inbox secret, version vderive(master, "inbox/<v>")The X25519 private key of the inbox at that version.
pass seedderive(master, "passes")The source of every pass secret.
private link seedderive(master, "links")The source of every private link key.
local history keyderive(master, "history")Encrypts what the device keeps.

Info strings are UTF-8. <address> is the base58 address and <v> a decimal integer from 1.

derive.ts
import { createKeypairSigner, deriveKeys, keyDerivationMessage } from '@talaria/sdk'

declare const secretKey: Uint8Array

const signer = createKeypairSigner(secretKey)
const signature = await signer.signMessage(keyDerivationMessage(signer.address))
const keys = await deriveKeys(signer.address, signature, 1)
// keys.inbox.publicKey is the key open_inbox registers

Inbox keys#

The inbox secret for version v is used as an X25519 private key as it comes out of HKDF; its public key is what open_inbox registers for version 1 and rotate_inbox_key for each next version. On unlock the SDK reads the Inbox's key_version and derives every version from 1 to it, so messages sent to an older key still open.

Pass secrets#

The secret of the wallet's pass number i, counting purchases from 0, is

Text
secret_i = (int(derive(passSeed, "pass/<i>")) mod (r − 1)) + 1

with int reading the 32 bytes big-endian and r the BN254 scalar field modulus, 21888242871839275222246405745257275088548364400416034343698204186575808495617. The pass is bought with id_commitment = Poseidon(secret_i). To find its passes again, a device computes the commitments for i = 0, 1, 2, … up to the number of leaves in the pool and looks each one up among the public leaves. The proof covers what the secret proves.

Private link number i, counting from 0 on this wallet, has the X25519 private key derive(linkSeed, "link/<i>"). Its public key travels in the link's URL fragment, which a browser never sends to a server:

Text
<app>/l#key=<base64 public key>&name=<name>

name is optional. A device scans with the key of every link it has not revoked.

Creating a link first scans the Log to its head, then takes the index after the highest link the device holds and sends one message to the wallet's own inbox, with the text Private link: <name> (or Private link without a name) and the control { "type": "link-created", "index": …, "name": …, "url": … }. Revoking sends the text Private link revoked with { "type": "link-revoked", "index": … }. A device takes either control only when the writer is its own wallet: link-created adds the link with that index, name and URL, and link-revoked marks it revoked, so every device of the wallet holds the same links and stops scanning a revoked one. The device also tries the keys of every index from 0 up to the number of links it holds plus 7 that it does not hold; when one of those opens a message, it adds that link with the URL and name it reads from the message's target.link.

Sealing a message#

The body#

The plaintext is the UTF-8 JSON of one object. Its fields:

version1
Always 1.

Required

idstring (UUID)
The message id, shared by all its parts.

Required

partinteger
This part's position, from 0.

Required

totalinteger
How many parts the message has, 1 to 10,000.

Required

writeraddress
The writer's wallet.

Required

writerInboxKeybase64, 32 bytes
The writer's inbox public key when writing.

Required

writerKeyVersioninteger
Its version.

Required

sentAtstring (ISO 8601)
When the message was written, the same in every part.

Required

targetobject
{ "kind": "wallet", "wallet": … }, { "kind": "room", "roomId": … } or { "kind": "private-link", "link": … }.

Required

textstring
This part's text.

Required

controlany
A control message, such as a room invite.
authRecord<string, string>
Writer MACs, keyed by the base64 inbox key each one is for.

Required

The object is strict: an unknown field makes the body invalid and the entry is skipped.

Content and slots#

  1. Content key

    A fresh random 32-byte content key for this payload.

  2. Two slots

    Slot 0 is for the reader's key: the reader's inbox key, a room's key or a private link's key. Slot 1 is for the writer's own inbox key. For each, a fresh random X25519 ephemeral key pair, and shared = X25519(ephemeral secret, target public key).

  3. View tag

    SHA-256(shared)[0], one byte. It lets a scanner skip all but about one slot in 256 without decrypting.

  4. Wrap

    The slot key is derive(shared, "key-slot"). The wrapped key is a random 24-byte nonce, then XChaCha20-Poly1305 of the content key under the slot key, with no additional data: 72 bytes.

  5. Header

    The version byte, then each slot as ephemeral public key (32), view tag (1), wrapped key (72): 211 bytes.

  6. Encrypt

    The ciphertext is a random 24-byte nonce, then XChaCha20-Poly1305 of the body under the content key, with the 211-byte header as additional data.

The tag over the ciphertext authenticates the body and the whole slot header together: a changed ephemeral key, view tag or wrapped key in either slot fails to open. The bytes are laid out on Log entry format.

Opening#

For each entry, a scanner tries every key it holds (each inbox version, each unrevoked link key, each room key) against both slots: shared = X25519(own secret, ephemeral key); if SHA-256(shared)[0] matches the view tag, it unwraps the content key and opens the ciphertext with the header as additional data. A matching view tag that fails to open is a collision and the scanner moves on. Scanning covers the whole pass over the Log.

Writer MACs#

The writer proves inside the ciphertext which wallet wrote, without another wallet prompt. For each key the message is for, and for the writer's own inbox key, the writer adds

Text
auth[base64(K)] = base64(HMAC-SHA256(derive(X25519(writer inbox secret, K), "writer-auth"), body))

where body is the JSON of the body's fields without auth, in the order version, id, part, total, writer, writerInboxKey, writerKeyVersion, sentAt, target, text, then control when present. For a room, K runs over every member's inbox key.

The reader accepts a body only when all of these hold:

  1. the writer has an Inbox in the inbox directory, and writerInboxKey at writerKeyVersion was the writer's key at the entry's slot, by the Inbox's key history (valid from its event's slot until the next one);
  2. the MAC under the reader's own key matches: for a room, auth of one of the reader's inbox keys; otherwise auth of the key that opened the slot; computed as HMAC with derive(X25519(reader secret, writerInboxKey), "writer-auth");
  3. a body with target.kind wallet names the reader, unless the reader wrote it;
  4. the writer is not blocked on this device.

The inbox directory is every InboxOpened and InboxKeyRotated event in chain order. The SDK downloads it whole, the sealed segments of GET /inboxes/segments/:n and the tail of GET /inboxes/head, and folds it on the device into each wallet's Inbox and key history (findInbox, which downloads what is new at most every two seconds when a wallet is missing). The API never learns which wallet a device looks up.

Both ends of a pair can compute the same MAC: it authenticates the writer to the reader, and to no third party.

The self slot#

Slot 1 seals the content key to the writer's own current inbox key, and auth carries the MAC under that key. Any device that derives the writer's keys finds its sent messages in the Log and reads them back as sent, the way Restore rebuilds history.

Rooms#

A room key is a random 32-byte X25519 private key. A message to the room fills slot 0 for the room key's public key, so every member who holds the secret opens it with one key.

The key reaches members as an ordinary message to each one's wallet, with the text Invitation to <room name> and this control:

typestring
Marks the control as a room invite.

Required

roomRoom
The room as the writer holds it: id, name, members and keyVersion, with the writer's own state. Each member carries its wallet and name, with inbox null; lastMessage is null and unreadCount 0.

Required

secretKeybase64, 32 bytes
The room key.

Required

A member's device takes an invite only when its members include the reader, the writer is in members or among the room's members as the device holds it, and the secret is 32 bytes. An invite for a room it already holds is taken only from a current member and with a higher keyVersion. An invite the wallet itself wrote whose members leave the wallet out is its leaving: the device sets the room to left and drops its key. The room is joined when the device had already joined it or wrote the invite itself, and invited otherwise; sending to a room also marks it joined, so a restore brings back as joined every room the wallet created or wrote in.

  • Create: a new key at keyVersion 1, sent to every member.
  • Add: the same key at keyVersion + 1, sent to every member, the new one included.
  • Remove or leave: a new key at keyVersion + 1, sent to the remaining members; on leaving, the writer is no longer in members. A removed member is first sent a message with the text Removed from <room name> and the control { "type": "room-removed", "roomId": … }; from a current member, it sets the room to removed on the member's device and drops its key.

See Rooms.

Multi-part messages#

The SDK splits text into parts of at most 700 UTF-8 bytes, never inside a character. Each part is its own body (same id, total, writer, target and sentAt, its own part and text), its own payload and its own post with its own nullifier. countParts(text) gives the number.

A scanner collects parts by id and keeps only parts that agree on writer, total and target. When parts 0 to total − 1 are all present it joins their text in order and yields one message. Until then it resumes the next scan from the earliest Log index of an incomplete message.

Before proving a part, the SDK records its payload, pass and counter on the device. A retry reuses them, so a part is never sent twice with two nullifiers.

Local history#

Threads, rooms and their keys, private links, blocks, purchases and pending parts are kept as one JSON document, sealed with the local history key: a random 24-byte nonce, then XChaCha20-Poly1305 with no additional data. In a browser it is stored in IndexedDB, database talaria, object store encrypted, under the wallet's address; elsewhere in memory unless the app passes its own storage. The document opens only after the wallet signs the key derivation message on that device.