Skip to content

fix(pairing): require SAS confirmation before committing a pairing - #28

Draft
Jeon1691 wants to merge 1 commit into
masterfrom
Jeon1691/sec-pairing-sas
Draft

Jeon1691 wants to merge 1 commit into
masterfrom
Jeon1691/sec-pairing-sas

Conversation

@Jeon1691

Copy link
Copy Markdown
Owner

Problem

The relay generates the 6-digit pairing code. It returns the code in the create response and receives it in the join request, and the same code is the SPAKE2 password. Neither device compared anything out of band, so:

  1. A malicious or compromised relay could run one SPAKE2 session with each device. Key confirmation succeeds on both sides, because each device really did agree a key with the relay, and the relay then holds the room keys.
  2. Anyone who guessed the code joined silently. The creator never saw or confirmed who joined.

Attack scenario

The relay creates the room and learns the code. When the joiner connects, the relay answers each device's SPAKE2 message with its own and completes key_confirm on both sockets. It decrypts both device_bind messages, re-encrypts them under the other session's key, and sends pairing_complete. Each device stores room keys that the relay also knows, so the relay can read and re-encrypt all later sync traffic. A code guesser gets the same result as the creator's peer, without any relay compromise.

Resulting behavior

  • Crypto. clipsync-crypto derives sas_key = HKDF-SHA-256(SPAKE2 secret, salt = transcript hash, info = "clipsync/v1/sas"). It renders the key as 6 decimal digits: u64be(sas_key[0..8]) mod 10^6. Length and sampling are named constants. Two devices show the same code only when they ran SPAKE2 with each other.
  • Core. run_pairing calls a caller-supplied confirmation after it verifies the peer's key_confirm. The confirmation receives a SasCheck with the code, the peer device ID, and the relay-reported peer name. The device sends device_bind only after SasDecision::Confirmed. Room keys, the room record, the device token, and the sync config are written only after our device_bind went out and the peer's device_bind and pairing_complete arrived. Previously room keys were saved right after our own device_bind. A rejection sends error{code: "sas_rejected"}, which makes the relay drop the session, and returns an error. A timeout or a dropped prompt also stores nothing. PendingCreate::wait, create_room, join_room, App::room_create, and App::room_join now take the confirmation, so every caller must decide explicitly.
  • CLI. room join and room create --foreground print the code and the other device's name, then read one line. y/yes, or the code shown on the other device, confirms. Anything else, or end of input, rejects. The default background room create publishes the code in the existing pairing file (status confirm_sas). The worker then waits for clipsync room confirm [CODE] or clipsync room reject. --insecure-skip-sas is the explicit opt-out for scripts and is documented as removing the protection. --non-interactive fails closed at the prompt.
  • Desktop. The window shows the code and the peer name with "Codes match" and "Cancel". Cancelling clears the offer and states that nothing was stored.
  • Mobile FFI. Adds the SasVerifier callback interface plus create_room_verified and join_room_verified. The existing create_room() and join_room() keep working unchanged: they accept without comparing, log a warning, and are documented as unverified.
  • Docs. docs/security.md gains a "Verification code (SAS)" section covering what it protects against, the limit below, older peers, and the opt-outs. docs/protocol.md gains the derivation and commit order. docs/interfaces.md, docs/mobile.md, docs/assurance-case.md, and the README pairing section are updated.

Compatibility impact

  • Wire format: unchanged. The SAS is computed locally from existing transcript material, and sas_rejected uses the existing error frame.
  • Relay: unchanged.
  • Older peers: an updated device still pairs with an older one, because the older device's early device_bind is buffered until the local user confirms. The older device shows no code, so the comparison cannot be made; the docs say to treat such a pairing as unverified.
  • Persisted format: PairingWait gains optional sas, peer_device_name, and sas_decision fields (serde default, skipped when empty). Old files still load.
  • Rust API: the pairing functions gained a confirmation parameter, and PairingKeys gained a sas_key field. All in-workspace callers are updated.
  • UniFFI: additive only.

Verification

  • The new crypto tests were written first and failed to build against the unchanged code (missing SAS API). The new core and e2e tests also do not build against the old pairing signatures.
  • Crypto tests:
    • Honest peers derive the same SAS.
    • A relay MITM with the code, simulated as two seeded SPAKE2 sessions, passes key confirmation on both devices but yields different SAS values.
    • A guessed-code joiner's SAS differs from the intended device's.
    • An HKDF/rendering vector cross-checked with Python hmac/hashlib.
    • A seeded end-to-end vector pins the SPAKE2, transcript, HKDF, and rendering steps together.
  • Core tests (scripted relay):
    • No device_bind and nothing stored while the prompt is open.
    • Commit after confirmation, including when a pre-SAS-style peer binds and pairing_complete arrives early.
    • Rejection sends sas_rejected and never device_bind, with no room or *.secret files.
    • An unanswered prompt times out with nothing stored.
  • Relay e2e:
    • Every existing pairing test now confirms the SAS programmatically: each side compares the other's code.
    • New: both devices see the same code and correct peer IDs.
    • New: a joiner rejection leaves neither device with a room, keys, or credentials.
  • CLI integration:
    • Foreground create and join compare the codes over stdin.
    • The background room confirm <code> flow.
    • A mismatched room confirm and room reject store nothing on either device.
    • --insecure-skip-sas end to end.
  • Desktop: headless tests for the prompt and both buttons, and a full pairing with compared codes.
  • Mobile: the verified API rejects (nothing stored) and confirms; the legacy API still pairs.

Local results (macOS):

cargo +1.100.0 fmt --all -- --check                                        # ok
cargo +1.100.0 clippy --workspace --all-targets --locked -- -D warnings    # ok
cargo +1.100.0 test -p clipsync-crypto|storage|core|relay|cli|desktop|mobile --locked   # see below
cargo +1.95.0 check --workspace --all-targets --locked                     # ok

Test totals: crypto 27, storage 25, core 62, relay 74, cli 14, desktop 18, mobile 8, all passing. The foreground CLI pairing test was also run once with CLIPSYNC_TEST_DISPOSABLE_HOST=1 and passed. A rare race in the rejection path, where a late peer frame could drop the queued sas_rejected frame before it was flushed, was fixed: a bounded drain after close. The rejection tests then passed 8 times in a row.

Remaining limitations

  • Offline search by a relay. A device sends its SPAKE2 message before it has seen the peer's, so there is no commitment. A relay in the middle sees both honest messages before it picks its own message toward each device, and can search offline for messages that make the two 6-digit codes collide. That is a birthday search of about 2^10 cheap trials per side. This PR fully stops a guessed-code joiner and any relay that does not run that search, and turns a silent MITM into a targeted relay modification. Closing the gap needs a commitment to the SPAKE2 messages, which is a protocol change and is left for a follow-up PR. docs/security.md states this plainly and still recommends a trusted relay.
  • Unauthenticated peer name. The name shown next to the code is relay-reported; the docs say so.
  • Peer waits after a rejection. If one device rejects after the other already confirmed, the confirmed device stores nothing but waits until its pairing deadline (about 125 s), because the relay does not notify it.
  • Legacy mobile calls. create_room() and join_room() remain unverified for compatibility until apps move to the *_verified calls.

Derive a 6-digit short authentication string from the SPAKE2 secret and
transcript (HKDF label clipsync/v1/sas). Send DeviceBind and persist room
keys, room record, and credentials only after the local user confirms that
both devices show the same code; rejection or timeout stores nothing.

Add CLI prompts, room confirm/reject for background create, and
--insecure-skip-sas; a desktop verification panel; and a mobile SasVerifier
callback API while keeping the existing exports. No wire or relay change.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-advanced-security github-advanced-security AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CodeQL found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants