Skip to content

Technical Document

Paul edited this page Mar 27, 2024 · 1 revision

SSH-Sync Technical Documentation

SSH-Sync provides a streamlined solution for synchronizing SSH keys and configurations across multiple machines, leveraging secure cryptographic protocols. This revised documentation reflects corrections and further clarifications on SSH-Sync's operations, cryptographic security measures, and feature set.

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

SSH-Sync Architecture

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

Initial Setup

Upon setup, users create a unique ECDSA keypair for each machine. Additionally, a Master Key is generated per user, with each machine having its encrypted copy, allowing for secure communication and data transfer with the server.

Secure Communication

JWT Authentication

Communications with the server utilize JWTs, generated with the ES512 algorithm and the machine's private key, containing the username and machine name. This ensures that requests are authenticated and originate from authorized machines.

Secure Key Storage

Master Key and Keypair

  • Master Key: Unique to each user, encrypted with the public key of each machine, enabling secure data encryption on the server.
  • Keypair: Each machine has its own ECDSA keypair, facilitating secure communication and authentication with the server.

Data Transfer Process

  • Upload:

    • Server sends E_pubMachine(Master_Key).
    • Machine decrypts to obtain Master_Key using D_privMachine(E_pubMachine(Master_Key)).
    • Data encrypted with Master_Key and signed, E_privMachine(E_MasterKey(data)).
    • Server validates signature and stores encrypted data.
  • Download:

    • Server sends encrypted data and E_pubMachine(Master_Key).
    • Machine decrypts Master_Key and then the data, D_MasterKey(D_privMachine(encrypted_data)).

Adding New Machines

New machines are added through a secure exchange, ensuring only authorized additions:

  1. New machine requests addition.
  2. Existing machine validates the request through a challenge-response, facilitating the transfer of the encrypted Master Key to the new machine.

Technical Considerations

SSH Config Parsing

SSH-Sync is designed to parse SSH config files, adjusting configurations to suit different machines. This feature is aimed at simplifying setup across various environments.

Data Conflict Resolution

Note: SSH-Sync does not currently handle data conflicts (e.g., duplicate SSH configurations). Plans to address these issues are future-looking and will involve user input for resolution.

Cryptographic Notation Examples

For clarity, here are examples using mathematical cryptographic notation, as used in the original document:

  • Keypair Generation: Each machine generates an ECDSA keypair, Keypair = (PubKey, PrivKey).
  • Master Key Encryption: E_pubMachine(Master_Key) represents the encryption of the Master Key with the machine's public key.
  • Data Encryption and Signature: Encrypted and signed data is represented as E_privMachine(E_MasterKey(data)), ensuring that only the intended recipient can decrypt and verify the authenticity of the data.

Future Considerations

While SSH-Sync currently employs a server-client model, exploration into a P2P approach may offer benefits in direct synchronization scenarios, reducing reliance on centralized servers.