Skip to content
Sync protocol & cryptography

Sync protocol & cryptography

Paw synchronizes and clones vaults directly between devices on the same local network, without third-party servers, relay services, or cloud infrastructure.

This page documents the cryptographic architecture, post-quantum transport, and verification mechanisms used by the Paw Sync protocol.

Core security principles

  1. No secret transmission: Master passwords and age vault private keys are never transmitted across the network.
  2. Independent vault identities: Each device keeps its own independent age identity (identities/scrypt.age). Transferred credentials are re-encrypted with the recipient’s local key before being written to disk.
  3. Post-quantum transport: All network communication uses mutual TLS 1.3 with hybrid post-quantum key exchange (X25519 + ML-KEM-768) and post-quantum digital signatures (ML-DSA-44).
  4. Out-of-band verification: First-time device pairing requires mutual visual confirmation of a 6-digit verification code to prevent local network machine-in-the-middle attacks.

Protocol sequence

The diagram below illustrates the complete sequence when synchronizing two devices on the same local network:

    sequenceDiagram
    autonumber
    participant A as Device A (Planner)
    participant LAN as Local Network (LAN)
    participant B as Device B (Responder)

    Note over A,B: Phase 1: Local Discovery (mDNS)
    B->>LAN: Broadcast mDNS service advertisement (_paw-sync._tcp)
    A->>LAN: Query local network for Paw Sync services
    LAN-->>A: Discovered Device B IP & Port

    Note over A,B: Phase 2: Post-Quantum TLS 1.3 Handshake
    A->>B: Connect via HTTPS
    Note over A,B: Negotiate TLS 1.3 with X25519 + ML-KEM-768<br/>Exchange ML-DSA-44 certificates (Mutual TLS)
    A-->>B: Mutual TLS established (Encrypted tunnel)

    Note over A,B: Phase 3: Pairing & Mutual Verification (First connection)
    A->>B: Send pairing request with device name
    Note over A,B: Both devices compute 6-digit verification code
    A->>A: Display 6-digit code to User A
    B->>B: Display 6-digit code to User B
    A->>A: User A confirms code
    B->>B: User B confirms code
    A->>B: Confirm pairing completion
    Note over A,B: Store peer identities in sync-peers.age (vault-key encrypted)

    Note over A,B: Phase 4: Manifest & Diff Review
    A->>B: Request vault manifest
    B-->>A: Return manifest (item IDs, timestamps, content hashes)
    Note over A: Device A computes differences (new, modified, deleted)
    A->>A: User A reviews diff and selects actions (Push, Pull, Skip)

    Note over A,B: Phase 5: Item & Attachment Transfer
    A->>B: Transfer confirmed item updates & attachments
    Note over B: Decrypt from TLS, re-encrypt with local age key, write to disk
    B-->>A: Confirm operation completion
    A->>B: Notify Sync completed
  

Protocol phases explained

1. Local discovery (mDNS / Zeroconf)

When Sync is started, the responder advertises its presence using multicast DNS (mDNS) under the _paw-sync._tcp service type. The advertising payload includes the machine name and protocol version (paw-sync/1).

If mDNS multicast traffic is restricted or blocked on your network, Paw can generate a direct connection link (paw-sync://...) and display an ASCII QR code for direct manual connection via paw cli sync --link.

2. Post-quantum mutual TLS

Paw enforces TLS 1.3 for all synchronization requests. It requires:

  • Key encapsulation: Hybrid X25519MLKEM768, combining classical X25519 with NIST ML-KEM-768 (Module-Lattice-Based Key-Encapsulation Mechanism).
  • Authentication: Mutual authentication using X.509 certificates generated with NIST ML-DSA-44 (Module-Lattice-Based Digital Signature Algorithm).

Every session generates an ephemeral TLS certificate bound to the device’s persistent Sync identity: an ML-DSA-44 key pair stored in sync.age inside the vault directory, encrypted with the vault key. During Sync clone, a temporary identity is generated for the session and persisted as the new vault’s sync.age when the clone completes.

3. Pairing and persistent trust

When connecting to an unrecognized device:

  1. Device A initiates a pairing request containing its display name and ML-DSA public key.
  2. Both devices compute a short 6-digit authentication code derived from the TLS session state and exchanged public keys.
  3. Users verify on their respective screens that the numbers match before approving the connection.
  4. Upon approval, both devices record the remote device’s name and ML-DSA public key in sync-peers.age, an age file encrypted with the vault key (never stored in plaintext).

Subsequent connections between paired devices authenticate silently using the ML-DSA keys recorded in sync-peers.age.

4. Manifest exchange and conflict resolution

Once authenticated, the planner requests the remote vault’s manifest:

  • The manifest contains item IDs, modification timestamps, version indices, and cryptographic hashes of item contents and attachments.
  • Neither device transfers the actual secret credentials at this stage.
  • The planner computes the differences and allows the user to review every change. The user explicitly chooses whether to copy the local version to the remote device, copy the remote version locally, or skip.

5. Secure item transfer and re-encryption

When executing the sync plan:

  • The source device reads the requested items and attachments from disk, decrypts them in memory using its own age identity, and streams them over the post-quantum TLS tunnel.
  • The receiving device receives the plaintext data in memory, immediately encrypts it using its own local age identity, and writes the newly encrypted files to its local storage directory.
  • Interrupted transfers are cancelled safely: Paw processes operations sequentially, ensuring that a dropped connection never leaves corrupt or partially written items.