SSH-Sync Technical Documentation

SSH-Sync provides a streamlined solution for synchronizing SSH keys and configurations across multiple machines, leveraging secure cryptographic protocols.

Overview

Architecture Diagram

SSH-Sync employs a server-client model to facilitate the secure transfer and synchronization of SSH keys:

• Setup and initial key exchange
• Configuring additional machines
• Secure requests for uploading and downloading keys

High-Level Concept

SSH-Sync automates the synchronization of SSH keys and configurations across different machines, eliminating the need for manual file transfers and adjustments due to changes in the operating system or file paths.

Server-Based Synchronization over P2P

A server-based model was chosen over P2P to avoid the complexity and inconvenience of manual machine-to-machine synchronization, providing a centralized solution for managing SSH keys.

Cryptographic Details

Default: Post-Quantum Cryptography

New machines are set up with post-quantum cryptography by default:

• Authentication: ML-DSA-65 (FIPS 204) — used to sign JWTs for server authentication
• Key Encapsulation: ML-KEM-768 (FIPS 203) — used to encrypt the master key per machine
• Data Encryption: AES-256-GCM — used to encrypt SSH key data at rest on the server

Classical ECDSA/ECDH-ES is still supported for machines set up with ssh-sync setup --classic or not yet migrated.

Initial Setup

Upon setup, users create a unique keypair for each machine (ML-DSA-65 + ML-KEM-768, or ECDSA if classic mode). Additionally, a Master Key (AES-256-GCM key) is generated per user, with each machine holding its own encrypted copy. This master key is used to encrypt SSH key data stored on the server.

JWT Authentication

Communications with the server use JWTs signed with the machine's private key (ML-DSA-65 or ECDSA), containing the username and machine name. This ensures requests are authenticated and originate from authorized machines.

Secure Key Storage

Master Key and Keypair

• Master Key: Unique per user; encrypted with each machine's public key (ML-KEM-768 or EC). The server stores one encrypted copy per registered machine.
• Keypair: Each machine has its own keypair for signing requests (ML-DSA-65 or ECDSA) and a separate encapsulation key (ML-KEM-768) for master key delivery.

Data Transfer Process

• Upload:

  • Server sends E_encapKey(Master_Key) for this machine.
  • Machine decrypts to obtain Master_Key.
  • SSH key data is encrypted: E_MasterKey(data).
  • Server stores the encrypted data.

• Download:

  • Server sends encrypted SSH key data and E_encapKey(Master_Key).
  • Machine decrypts Master_Key, then decrypts the SSH key data.

Adding New Machines

New machines are added through a secure challenge-response exchange:

1. New machine requests addition to the account, generating its keypair locally.
2. An existing authorized machine runs challenge-response with the challenge phrase from setup.
3. The existing machine encrypts the master key for the new machine's public key and sends it to the server.
4. The new machine can now authenticate and decrypt its copy of the master key.

Master Key Rotation

The rotate-master-key command generates a new master key and re-encrypts all SSH keys stored on the server:

1. A new master key is generated locally.
2. The new key is encrypted for every registered machine — using ML-KEM-768 encapsulation for post-quantum machines, or the machine's EC public key for classical machines.
3. All SSH key data on the server is re-encrypted with the new master key.
4. Other machines automatically apply the new master key on their next download or sync.

Post-Quantum Migration

Machines originally set up with classical ECDSA can migrate to post-quantum cryptography using ssh-sync migrate:

1. The current master key is decrypted using the existing EC keypair.
2. A new ML-DSA-65 + ML-KEM-768 keypair is generated.
3. The master key is re-encrypted with the new ML-KEM-768 encapsulation key.
4. The new public key is uploaded to the server.

SSH key data on the server is unaffected — AES-256-GCM is already quantum-resistant.

Commands

Command	Description
setup	Initial setup; generates keypair and registers machine. Use --classic for ECDSA.
upload	Upload local SSH keys and config to the server.
download	Download SSH keys and config from the server.
sync	Bidirectional sync; newer timestamp wins automatically.
challenge-response	Authorize a new machine from an existing one.
list-machines	List all machines registered to the account.
remove-machine	Deregister a machine from the account.
reset	Remove the current machine from the account and clear local ssh-sync data.
migrate	Migrate this machine's keypair from ECDSA to post-quantum.
rotate-master-key	Generate a new master key and re-encrypt all server-stored SSH keys.
interactive	TUI for interactively managing SSH keys.

Sync Logic

The sync command compares the local .ssh directory against the server's key list using modification timestamps (truncated to second precision for filesystem compatibility):

• Local only: uploaded to the server.
• Server only: downloaded locally.
• Both present, timestamps differ: newer version wins automatically.
• Timestamps equal, content differs: server version wins to prevent silent overwrites from mtime manipulation.

The SSH config and known_hosts are always written from the server after a sync.

Technical Considerations

SSH Config Parsing

SSH-Sync parses SSH config files and adjusts IdentityFile paths to suit the target machine's filesystem layout when downloading or syncing.

Data Conflict Resolution

During download, if a file already exists locally with different content, ssh-sync prompts the user to overwrite, skip, or save the server version with a .duplicate extension for manual review.

During sync, conflicts are resolved automatically by timestamp — no user prompting is needed.