pairing

Overview ¶

Package pairing pkg/skychat/pairing/crypto.go c4-app-chat body encryption for chat-pair feeds.

Threat model: the pair feed lives at a publicly-known DMSG port under the publisher's PK, and any peer who learns the publisher PK + port can attempt to subscribe. The publisher-side allowlist (CXO TreeStore SubscriberAllowlist, added in #2378) gates read access to the feed at the connection layer. This file adds a belt-and-suspenders layer at the message-content layer:

• Each Pair derives a 32-byte symmetric key from ECDH(my_sk, peer_pk). Both sides compute the same key from ECDH(my_pk, peer_sk) and ECDH(peer_pk, my_sk) — that's the symmetry property of ECDH.
• Every leaf published into the pair feed is sealed with ChaCha20-Poly1305 AEAD, with a fresh random 12-byte nonce prepended to the ciphertext: [nonce | ct+tag].

What is encrypted:

• The Message JSON body. The leaf bytes stored in CXO are ciphertext; subscribers decrypt before json.Unmarshal.

What is NOT encrypted:

• The path: msgs/<unix-nanos>/<seq>. Timestamp + ordering are metadata; an observer who already breached the allowlist would learn the timing pattern of messages but not their content.

secp256k1 + ChaCha20-Poly1305: the skywire identity uses secp256k1 keys, not Curve25519, so we can't use NaCl box directly. skycoin/cipher.ECDH does the secp256k1 scalar-mult and SHA256s the raw shared point — that yields a 32-byte key suitable as the ChaCha20-Poly1305 key directly. No HKDF needed because we have a single fixed use (this pair) per derived key.

The static key is now the FALLBACK, not the norm ¶

derivePairKey's output is a pure function of two long-term identity keys, which means it never changes and can be recomputed forever — so leaking a visor's identity secret retroactively opens every DM it ever exchanged. epoch.go / ratchet.go replace it with short-lived epoch keys whose secret halves are destroyed on rotation.

The static key survives for exactly two jobs, both compatibility:

• Messages already on a feed, published before this visor (or the peer) had a ratchet. Those leaves stay in the CXO tree forever and must keep opening.
• A peer running a build without ratchet support, which never announces and never sends an epoch envelope.

sealEnvelope tags every new message with the epoch it used, and openEnvelope routes a tagged blob to the ring and an untagged one to the static key. A pair falls back only when it genuinely has no epoch; it never downgrades once one exists.

Package pairing pkg/skychat/pairing/epoch.go c4-app-chat forward-secret epoch keys for a chat pair.

What was wrong with one key per pair ¶

crypto.go derives the pair key as ECDH(my_sk, peer_pk). That is a pure function of two long-term identity keys, so it is the SAME key for every message the pair will ever exchange, and it can be recomputed from either side's identity secret at any point in the future. The consequences are worse than "no forward secrecy" in the abstract:

• Pair feeds are CXO trees. Every ciphertext ever published stays in the tree and is served to anyone the allowlist admits. An observer only has to capture the feed once.
• A visor's identity secret sits in its config file and is the same key used for dmsg, transports, and RPC auth — a broad surface with many ways to leak that have nothing to do with chat.
• Put together: leaking that one file, ever, retroactively decrypts every DM the visor ever sent or received. Rotating it doesn't help either, because the old key still opens the old feed.

Epochs ¶

Both sides now publish a short-lived RATCHET public key on their own feed (ratchet.go) and re-publish it periodically. The key for an epoch is derived from the two current ratchet keys:

epochSecret = ECDH(my_ratchet_sk, peer_ratchet_pk)
epochKey    = HKDF-SHA256(epochSecret, salt=epochID, info="skychat:pair-epoch:v1")

ECDH's symmetry gives both sides the same secret from their own secret half and the other's public half, exactly as before — but now neither half is a long-term identity key. When a side rotates its ratchet key it DELETES the old secret, and from that moment the epochs that used it cannot be re-derived by anyone, including the parties themselves. The identity keys are no longer sufficient to open past traffic, which is the whole point.

This is the DH half of a Double Ratchet and not the symmetric half: there is no per-message chain key, so within one epoch a compromise still reveals that epoch. Bounding an epoch is what ratchetMaxAge and ratchetMaxMessages are for. A per-message chain would need in-order delivery guarantees the CXO feed does not offer (leaves arrive in tree order after a resync, not send order), so the epoch is the unit here.

Why HKDF here and not in crypto.go ¶

The legacy path used the raw ECDH output as the AEAD key, justified by there being exactly one use per derived secret. That stops being true with epochs: the same (my_ratchet, peer_ratchet) pair identifies an epoch, and mixing the epoch ID in through a KDF is what keeps the key bound to it. It also gives a versioned info string, so a future change of construction is a different key rather than a silent reinterpretation of the same bytes.

Package pairing pkg/skychat/pairing/manager.go c4-app-chat a visor's collection of chat pairs.

The Manager owns the bbolt Store and a map[cipher.PubKey]*Pair of live runtime state. It glues persistence to lifecycle: Add records a pair and brings up its Pair, Resume walks the store on startup and reopens every active pair, Remove transitions a record to revoked and tears down its Pair.

The pairing handshake itself (sending invite messages over legacy skychat, awaiting ack, transitioning pending→active) is intentionally out of scope — it lives one layer up in PR-3, where it can drive the Manager via its public surface.

Package pairing pkg/skychat/pairing/pair.go c4-app-chat pair's runtime state.

One CXO node per pair side, listening on the deterministic pair port (ComputePairPort(my_pk, peer_pk)). The node hosts both roles:

• Publisher: shares this side's outbox feed, with an allowlist of exactly the peer's PK. Only the peer may subscribe and read.
• Subscriber: connected to the peer's outbox feed (same port, peer's PK as the feed identity). Receives messages from peer.

One node per pair (not two) keeps the DMSG port allocation simple and matches the symmetric protocol: both ends listen on the same port number, both ends dial the other at that port. The CXO node multiplexes publisher and subscriber roles by feed PK.

Lifecycle: Open creates the publisher (ready to accept the peer's subscribe) and constructs the subscriber attached to the publisher's node. Connect dials the peer's node and registers the inbound subscribe. Open + Connect are split so the pairing handshake (PR-5+) can stage the publisher before the peer is known to be ready.

Package pairing pkg/skychat/pairing/ports.go c4-app-chat DMSG port allocation for chat-pair feeds.

Each unordered pair of visor public keys (Alice, Bob) maps to a stable DMSG port. Both sides of the pair compute the same number from public information alone, so no out-of-band port negotiation is needed.

Port plan: one port per pair, in [PortBase, PortBase+PortSpan). Each side's CXO node listens on this single port and hosts both roles — Alice publishes her own pair-with-Bob feed and subscribes to Bob's pair-with-Alice feed on the same node, with Bob's node doing the symmetric thing on the same port number on his side. One port suffices because publisher and subscriber operate on distinct feed PKs (each side's own PK), so the CXO node multiplexes them on the single DMSG conn.

The range sits clear of the system DMSG port table (everything <300 plus reserved ports around 80 / 100 / 136). Collisions with the reserved set are walked past so a pair can always Listen.

Package pairing pkg/skychat/pairing/ratchet.go c4-app-chat the per-pair ratchet: which short-lived keys we hold, which the peer has announced, and when to move on.

The announcement ¶

Each side publishes its current ratchet PUBLIC key as a leaf on its own feed, at ratchet/<generation>. That is the whole handshake — there is no round trip, no negotiation, and no ordering requirement. Each side derives every epoch it can from (its own ratchet secrets) × (the peer's announced ratchet keys), so the two ends converge on the same set of epoch keys whichever order the leaves arrive in.

Announcements are signed with the visor's IDENTITY key. The CXO Root that carries the leaf is already signed by the feed owner, so this is belt-and-braces — but the field it protects is the one that decides which key we derive, and an attacker who could rewrite a leaf without the signature would be able to steer us onto a key of their choosing. The cost is one signature per rotation, which is hours apart.

Why announcements are re-published, not just published once ¶

A pair's CXO tree is the durable record: a subscriber that resyncs walks the whole tree and sees every ratchet/<gen> leaf, including ones published while it was offline. Keeping the past generations in the tree (rather than overwriting one path) is deliberate — a peer that was away for three of our rotations still needs the announcements for the epochs whose messages it hasn't read yet, and pruning them would make that history unopenable for a reason unrelated to forward secrecy.

The ratchet SECRETS are the ones that get dropped, and dropping them is what makes those old epochs forward-secret: the announcement being public is fine, since a public key alone derives nothing.

What is deliberately not here ¶

No per-message chain key. See epoch.go for why the epoch, not the message, is the unit of forward secrecy on a CXO feed.

Package pairing pkg/skychat/pairing/store.go c4-app-chat persistence for chat pairs.

One bucket "pairs" with key = peer PK hex, value = JSON Record. Crash-safe by virtue of bolt's single-writer semantics: each Put is one transaction, each Resume is a read.

The store is intentionally narrow — Add / Get / List / Delete / Set — so the lifecycle code in pair.go can drive policy (e.g. when to transition status from "pending" to "active") without the store having to know about it.

Package pairing pkg/skychat/pairing/store_seal.go c4-app-chat sealing a pair's ratchet secrets at rest.

The pair store gained something worth protecting when the ratchet landed. Before it, a Record held only metadata — peer PK, port, status, timestamps — and the one secret in the system (the static pair key) was never stored at all because it could be recomputed from the visor's identity key on demand. Recomputable was the problem the ratchet exists to fix, and the fix means the secrets now have to live somewhere.

What is at stake if they are stored in the clear: the current ratchet SECRET (opens the current epoch, and every future one until the next rotation) and the epoch-key ring (opens up to ratchetRingCap epochs of feed history). Writing those as plaintext JSON would hand an attacker with read access to pairs.db exactly what the ratchet was built to deny them, without needing the identity key at all — a strictly worse position than before the feature.

Same construction as the group store (cmd/apps/skychat/group/ store_seal.go), deliberately, so there is one at-rest idiom in this app: HKDF-SHA256 from the visor's secret key into a ChaCha20-Poly1305 key, per-record AAD binding a blob to the slot it belongs in, and a best-effort open so a record whose secrets won't decrypt still loads its metadata.

Same honest limit, too: the sealing key derives from the visor SK, which lives in the config file on the same disk. This raises the bar from "read one file" to "read two specific files on the same host". It is not disk encryption and not a passphrase.