diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7a39f8a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,30 @@ + +# Contributing to SSH-Sync + +We welcome contributions to the SSH-Sync project! Whether you're looking to fix bugs, add new features, or improve documentation, your help is appreciated. Here's how you can contribute: + +## Reporting Issues + +If you encounter a bug or have a suggestion for improving SSH-Sync, please first check the [issue tracker](https://github.com/therealpaulgg/ssh-sync/issues) to see if it has already been reported. If not, feel free to open a new issue. Please provide as much detail as possible to help us understand the problem or enhancement. + +## Submitting Pull Requests + +We accept contributions through pull requests. Here are the steps to submit your contributions: + +1. Fork the repository. +2. Create a new branch for your feature or bug fix. +3. Make your changes. +4. Ensure your code follows the project's coding standards. +5. Submit a pull request against the main branch. + +Please provide a clear description of the problem and solution, including any relevant issue numbers. + +## Code of Conduct + +We expect all contributors to adhere to our Code of Conduct. By participating in this project, you agree to abide by its terms. + +## Questions? + +If you have any questions about contributing, please feel free to ask in the issue tracker or reach out to the maintainers. + +Thank you for your interest in contributing to SSH-Sync! diff --git a/README.md b/README.md index 0d3fd28..3cd7c8f 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,142 @@ -# SSH Sync -A CLI application to sync SSH keys along with a SSH configuration between machines on-demand. +# ssh-sync: Seamless SSH Key Management -Also part of this project: +ssh-sync is a powerful CLI tool designed to simplify the way you manage and synchronize your SSH keys and configurations across multiple machines. With ssh-sync, gone are the days of manually copying SSH keys or adjusting configurations when switching devices. Whether you're moving between workstations or setting up a new machine, ssh-sync ensures your SSH environment is up and running effortlessly. -[https://github.com/therealpaulgg/ssh-sync-server](https://github.com/therealpaulgg/ssh-sync-server) -[https://github.com/therealpaulgg/ssh-sync-db](https://github.com/therealpaulgg/ssh-sync-db) +[![release](https://github.com/therealpaulgg/ssh-sync/actions/workflows/release.yml/badge.svg)](https://github.com/therealpaulgg/ssh-sync/actions/workflows/release.yml) -## Diagram +## Quick Start -This diagram depicts the following: +### Installation -1. Initial user setup with server -2. Sequence diagram illustrating a user configuring a new PC -3. Authenticated download request -4. Authenticated upload request +ssh-sync is available on Windows, macOS, and Linux. Choose the installation method that best suits your operating system: -![svg-of-ssh-sync-architecture](https://raw.githubusercontent.com/therealpaulgg/ssh-sync/main/docs/diagrams.svg) +#### Windows -## High-Level Concept +Install ssh-sync using Winget: -You have a computer which has SSH keys and configuration on them, and on a secondary machine you would like these keys so you are able to access your servers from another machine. This often involves copy-pasting files and also rewriting an SSH configuration file because file paths change, or the operating system changes. This can be quite tedious. This program aims to replace the manual steps involved by allowing a secure method of transferring keys and keeping them all synced in a remote server. +```shell +winget install ssh-sync +``` -## Why not P2P? +#### macOS -P2P was considered (and may still be done at a later date) but ultimately dismissed because every key sync request would have to involve two machines, which would get tedious quickly. The main idea is a transaction involving two machines at the same time would only have to be done once (to allow a new machine access to a user's keys). After this point, the new machine can communicate to the server freely, uploading and downloading new keys. A P2P implementation would mean that a machine would have to do a 'handshake' with another machine each time. There would also be no central source to keep key data synchronized. +ssh-sync can be installed using Homebrew: -# Technical Details (Crypto) +```shell +brew tap therealpaulgg/ssh-sync +brew install ssh-sync +``` -## Initial Setup +#### Linux -On initial setup, a user will be asked to provide a username and name for the current machine. A ECDSA keypair will also be created, and the user's public key will be uploaded to the server, corresponding to the username and machine name. From this point on, the user will be able to communicate to the server and upload/download keys, as well as config data. +For Linux users, download the appropriate package from our [GitHub Releases](https://github.com/therealpaulgg/ssh-sync/releases) page: -## Communication to Server +- For Debian-based distributions (e.g., Ubuntu): -### JWT for Requests +```shell +wget +sudo dpkg -i ssh-sync_0.3.8_amd64.deb +``` -All requests to the server (besides initial setup) will be done with a JWT. This JWT will be crafted on the client-side. It will be crafted using the ES512 algorithm, using the user's private key. The token will then be sent to the server, and validated with the user's public key. The crafted token needs to contain the following: +- For RPM-based distributions (e.g., Fedora, CentOS): -- Username -- Machine Name +```shell +wget +sudo rpm -i ssh-sync-v0.3.8-1.x86_64.rpm +``` -the server will then look up the public key corresponding to the username and machine name provided, and attempt to validate the signature. It will be impossible for someone to forge a JWT for a particular user/machine pair because it would require the private key. +## Getting Started with SSH-Sync -For example, if Eve crafts a JWT that says `{"username": "Alice", "machineName": "my-computer"}`, the server will attempt to verify the JWT using Alice's 'my-computer' keypair. Eve cannot impersonate Alice unless she gets her hands on Alice's private key. +SSH-Sync makes managing and syncing your SSH keys across multiple machines effortless. Here's how to get started: -## Storing Keys On The Server Securely +### Setup -### Master Key +First, you'll need to set up SSH-Sync on your machine. Run the following command: -Each user will have a 'Master Key'. This will be a unique symmetric key. Each client will have the master key on their machine, encrypted with their public key. For example, on computer A there would be `E_pubA(master_key)` and on computer B `E_pubB(master_key)`. All of the user's data (SSH keys) will be stored on the server in an encrypted AES 256 GCM format. This data can only be decrypted with the master symmetric key, which can only be decrypted by the user using one of their user/machine keypairs. +```shell +ssh-sync setup +``` -NOTE: the master key was previously stored on the server, but this was found to be redundant and unnecessary. It is practically just as secure to keep the master key on each machine (encrypted or even unencrypted theoretically). If someone has the public/private keypair, they would be able to easily retrieve the master key for that machine from the server anyways. +During setup, you'll be prompted to choose between using your own server or the sshsync.io hosted server. Next, you'll specify whether you have an existing account. If you do not, you'll be guided through creating an account, naming your machine, and generating a keypair for it. If you have an existing account, you'll be given a challenge phrase, which you must enter on another one of your machines using the `challenge-response` command. This process securely adds your new machine to your SSH-Sync account. -#### Upload +### Uploading Keys -Whenever the user wants to upload new data, the server will send the encrypted master key. The user will then decrypt the master key, and send encrypted keys to the server. +To upload your SSH keys and configuration to the server, run: -Server sends: `E_pubMachine(master_key)` +```shell +ssh-sync upload +``` -Machine decrypts master key, `D_privMachine(E_pubMachine(master_key))` +This command securely transmits your SSH keys and configuration to the chosen server, making them accessible from your other machines. -Machine encrypts keys with `master_key` and also signs the data. +### Downloading Keys -`E_privMachine(E_masterKey(plaintext))` +To download your SSH keys to a new or existing machine, ensuring it's set up for remote access, use: -Server receives this data and validates the signature: +```shell +ssh-sync download +``` -`D_pubMachine(ciphertext)` +This command fetches your SSH keys from the server, setting up your SSH environment on the machine. -The server will then store this `ciphertext`. +### Challenge Response -#### Download +If setting up a new machine with an existing account, use: -Whenever the user wants to download data, the server will send all the user's data in encrypted format, as well as the encrypted master key. +```shell +ssh-sync challenge-response +``` -The user, once it receives the data, will decrypt the master key using their private key, and then decrypt the ciphertext. +Enter the challenge phrase received during the setup of another machine. This verifies your new machine and securely transfers the necessary keys. -Server sends: `E_pubMachine(ciphertext), E_pubMachine(master_key)` +### Managing Machines -Machine decrypts master key, `D_privMachine(E_pubMachine(master_key))` +To list all machines configured with your SSH-Sync account, run: -Machine decrypts ciphertext. +```shell +ssh-sync list-machines +``` -`D_masterKey(D_privMachine(ciphertext))` +If you need to remove a machine from your SSH-Sync account, use: -## Adding New Machines +```shell +ssh-sync remove-machine +``` -Adding a new machine will require one of the user's other machines. The new machine will make a request to the server to be added. The server will then respond with some sort of challenge, requesting that the user enters a phrase on one of their old machines. Once the user enters the phrase on their old machine, the server will then allow them to upload a public keypair so they can do communication with the server. The old machine will need to be involved a little longer so that it can decrypt the master key, and upload a new master key using this new machine's public key. Here is the full process laid out: +Specify the machine you wish to remove following the command. -Machine B requests to be added to allowed clients -Server gives Machine B a challenge phrase which must be entered on Machine A -Challenge phrase is entered on Machine A. Machine A awaits response from server (Machine B's public key) -Machine B generates keypair and uploads public key to server. -Server saves B's public key and then sends `E_aPub(master_key)` & B's public key to Machine A. -Machine A does `D_aPriv(enc_master_key)`, and then sends `E_bPub(master_key)` to the server. -Server then saves this new encrypted master key. +### Reset -# Other Technical Details +To remove the current machine from your account and clear all SSH-Sync data: -## SSH Config Parsing +```shell +ssh-sync reset +``` -Part of the syncing process will be where the program parses a user's SSH config file, and then sends the parsed format over to the server. Other machines, when syncing, will be able to have new config files generated for them based on what is in the server (and the CLI will handle changing user directories & OS changes). +This command is useful if you're decommissioning a machine or wish to start fresh. -## Data Conflicts +By following these steps, you can seamlessly sync and manage your SSH keys across all your machines with SSH-Sync. -TODO: after parsing SSH config, if there are duplicate entries, attempt to merge, but with conflicts, ask user how to resolve. +## How ssh-sync Works -TODO: what if duplicate keys get uploaded? ask user to replace/skip +ssh-sync leverages a client-server model to store and synchronize your SSH keys securely. The diagram below outlines the ssh-sync architecture and its workflow: -# P2P Concept +![ssh-sync Architecture](https://raw.githubusercontent.com/therealpaulgg/ssh-sync/main/docs/diagrams.svg) -If P2P was to be implemented, a lot of the crypto needed for the server implementation would be unnecessary. This is how a request would probably go: +For a deep dive into the technicalities of ssh-sync, including its security model, data storage, and key synchronization process, check out our [Wiki](https://github.com/therealpaulgg/ssh-sync/wiki). -Machine B wants Machine A's keys and config. -Machine A challenges Machine B with a phrase. -Machine B responds to challenge, and sends its public key. -Assuming challenge is passed, Machine A encrypts its data using EC-DH-A256GCM (Machine B public key) and sends it over to Machine B. -Machine B would receive the data, decrypt it, and the program would manage things as necessary. +## Why Choose ssh-sync? -All the other functionality of the program (i.e SSH config parser) would remain the same. +- **Simplify SSH Key Management:** Easily sync your SSH keys and configurations across all your devices. +- **Enhanced Security:** ssh-sync uses advanced cryptographic techniques to ensure your SSH keys are securely transmitted and stored. +- **Effortless Setup:** With support for Windows, macOS, and Linux, setting up ssh-sync is straightforward, regardless of your operating system. + +## Contributing + +ssh-sync is an open-source project, and contributions are welcome! If you're interested in contributing, please check out our [contribution guidelines](https://github.com/therealpaulgg/ssh-sync/blob/main/CONTRIBUTING.md). + +## License + +ssh-sync is released under the [MIT License](https://github.com/therealpaulgg/ssh-sync/blob/main/LICENSE.txt). diff --git a/docs/index.html b/docs/index.html index 5e5c56a..3b691f7 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,50 +1,78 @@ -

SSH Sync

-

A CLI application to sync SSH keys along with a SSH configuration between machines on-demand.

-

High-Level Concept

-

You have a computer which has SSH keys and configuration on them, and on a secondary machine you would like these keys so you are able to access your servers from another machine. This often involves copy-pasting files and also rewriting an SSH configuration file because file paths change, or the operating system changes. This can be quite tedious. This program aims to replace the manual steps involved by allowing a secure method of transferring keys and keeping them all synced in a remote server.

-

Why not P2P?

-

P2P was considered (and may still be done at a later date) but ultimately dismissed because every key sync request would have to involve two machines, which would get tedious quickly. The main idea is a transaction involving two machines at the same time would only have to be done once (to allow a new machine access to a user's keys). After this point, the new machine can communicate to the server freely, uploading and downloading new keys. A P2P implementation would mean that a machine would have to do a 'handshake' with another machine each time. There would also be no central source to keep key data synchronized.

-

Technical Details (Crypto)

-

Initial Setup

-

On initial setup, a user will be asked to provide a username and name for the current machine. A ECDSA keypair will also be created, and the user's public key will be uploaded to the server, corresponding to the username and machine name. From this point on, the user will be able to communicate to the server and upload/download keys, as well as config data.

-

Communication to Server

-

JWT for Requests

-

All requests to the server (besides initial setup) will be done with a JWT. This JWT will be crafted on the client-side. It will be crafted using the ES512 algorithm, using the user's private key. The token will then be sent to the server, and validated with the user's public key. The crafted token needs to contain the following:

+

ssh-sync: Seamless SSH Key Management

+

ssh-sync is a powerful CLI tool designed to simplify the way you manage and synchronize your SSH keys and configurations across multiple machines. With ssh-sync, gone are the days of manually copying SSH keys or adjusting configurations when switching devices. Whether you're moving between workstations or setting up a new machine, ssh-sync ensures your SSH environment is up and running effortlessly.

+

Quick Start

+

Installation

+

ssh-sync is available on Windows, macOS, and Linux. Choose the installation method that best suits your operating system:

+

Windows

+

Install ssh-sync using Winget:

+
winget install ssh-sync
+
+

macOS

+

ssh-sync can be installed using Homebrew:

+
brew tap therealpaulgg/ssh-sync
+brew install ssh-sync
+
+

Linux

+

For Linux users, download the appropriate package from our GitHub Releases page:

-

the server will then look up the public key corresponding to the username and machine name provided, and attempt to validate the signature. It will be impossible for someone to forge a JWT for a particular user/machine pair because it would require the private key.

-

For example, if Eve crafts a JWT that says {"username": "Alice", "machineName": "my-computer"}, the server will attempt to verify the JWT using Alice's 'my-computer' keypair. Eve cannot impersonate Alice unless she gets her hands on Alice's private key.

-

Storing Keys On The Server Securely

-

Master Key

-

Each user will have a 'Master Key'. This will be a unique symmetric key. This symmetric key will be stored on the server, one copy for each keypair. For example, on the server, there would be E_pubA(master_key) and E_pubB(master_key). All of the user's data will be stored on the server in an encrypted AES 256 GCM format. This data can only be decrypted with the master symmetric key, which can only be decrypted by the user using one of their user/machine keypairs.

-

Upload

-

Whenever the user wants to upload new data, the server will send the encrypted master key. The user will then decrypt the master key, and send encrypted keys to the server.

-

Server sends: E_pubMachine(master_key)

-

Machine decrypts master key, D_privMachine(E_pubMachine(master_key))

-

Machine encrypts keys with master_key and also signs the data.

-

E_privMachine(E_masterKey(plaintext))

-

Server receives this data and validates the signature:

-

D_pubMachine(ciphertext)

-

The server will then store this ciphertext.

-

Download

-

Whenever the user wants to download data, the server will send all the user's data in encrypted format, as well as the encrypted master key.

-

The user, once it receives the data, will decrypt the master key using their private key, and then decrypt the ciphertext.

-

Server sends: E_pubMachine(ciphertext), E_pubMachine(master_key)

-

Machine decrypts master key, D_privMachine(E_pubMachine(master_key))

-

Machine decrypts ciphertext.

-

D_masterKey(D_privMachine(ciphertext))

-

Adding New Machines

-

Adding a new machine will require one of the user's other machines. The new machine will make a request to the server to be added. The server will then respond with some sort of challenge, requesting that the user enters a phrase on one of their old machines. Once the user enters the phrase on their old machine, the server will then allow them to upload a public keypair so they can do communication with the server. The old machine will need to be involved a little longer so that it can decrypt the master key, and upload a new master key using this new machine's public key. Here is the full process laid out:

-

Machine B requests to be added to allowed clients
Server gives Machine B a challenge phrase which must be entered on Machine A
Challenge phrase is entered on Machine A. Machine A awaits response from server (Machine B's public key)
Machine B generates keypair and uploads public key to server.
Server saves B's public key and then sends E_aPub(master_key) & B's public key to Machine A.
Machine A does D_aPriv(enc_master_key), and then sends E_bPub(master_key) to the server.
Server then saves this new encrypted master key.

-

Other Technical Details

-

SSH Config Parsing

-

Part of the syncing process will be where the program parses a user's SSH config file, and then sends the parsed format over to the server. Other machines, when syncing, will be able to have new config files generated for them based on what is in the server (and the CLI will handle changing user directories & OS changes).

-

Data Conflicts

-

TODO: after parsing SSH config, if there are duplicate entries, attempt to merge, but with conflicts, ask user how to resolve.

-

TODO: what if duplicate keys get uploaded? ask user to replace/skip

-

P2P Concept

-

If P2P was to be implemented, a lot of the crypto needed for the server implementation would be unnecessary. This is how a request would probably go:

-

Machine B wants Machine A's keys and config.
Machine A challenges Machine B with a phrase.
Machine B responds to challenge, and sends its public key.
Assuming challenge is passed, Machine A encrypts its data using EC-DH-A256GCM (Machine B public key) and sends it over to Machine B.
Machine B would receive the data, decrypt it, and the program would manage things as necessary.

-

All the other functionality of the program (i.e SSH config parser) would remain the same.

+
wget <link-to-.deb-file>
+sudo dpkg -i ssh-sync_0.3.8_amd64.deb
+
+ +
wget <link-to-.rpm-file>
+sudo rpm -i ssh-sync-v0.3.8-1.x86_64.rpm
+
+

Getting Started with SSH-Sync

+

SSH-Sync makes managing and syncing your SSH keys across multiple machines effortless. Here's how to get started:

+

Setup

+

First, you'll need to set up SSH-Sync on your machine. Run the following command:

+
ssh-sync setup
+
+

During setup, you'll be prompted to choose between using your own server or the sshsync.io hosted server. Next, you'll specify whether you have an existing account. If you do not, you'll be guided through creating an account, naming your machine, and generating a keypair for it. If you have an existing account, you'll be given a challenge phrase, which you must enter on another one of your machines using the challenge-response command. This process securely adds your new machine to your SSH-Sync account.

+

Uploading Keys

+

To upload your SSH keys and configuration to the server, run:

+
ssh-sync upload
+
+

This command securely transmits your SSH keys and configuration to the chosen server, making them accessible from your other machines.

+

Downloading Keys

+

To download your SSH keys to a new or existing machine, ensuring it's set up for remote access, use:

+
ssh-sync download
+
+

This command fetches your SSH keys from the server, setting up your SSH environment on the machine.

+

Challenge Response

+

If setting up a new machine with an existing account, use:

+
ssh-sync challenge-response
+
+

Enter the challenge phrase received during the setup of another machine. This verifies your new machine and securely transfers the necessary keys.

+

Managing Machines

+

To list all machines configured with your SSH-Sync account, run:

+
ssh-sync list-machines
+
+

If you need to remove a machine from your SSH-Sync account, use:

+
ssh-sync remove-machine
+
+

Specify the machine you wish to remove following the command.

+

Reset

+

To remove the current machine from your account and clear all SSH-Sync data:

+
ssh-sync reset
+
+

This command is useful if you're decommissioning a machine or wish to start fresh.

+

By following these steps, you can seamlessly sync and manage your SSH keys across all your machines with SSH-Sync.

+

How ssh-sync Works

+

ssh-sync leverages a client-server model to store and synchronize your SSH keys securely. The diagram below outlines the ssh-sync architecture and its workflow:

+

ssh-sync Architecture

+

For a deep dive into the technicalities of ssh-sync, including its security model, data storage, and key synchronization process, check out our Wiki.

+

Why Choose ssh-sync?

+ +

Contributing

+

ssh-sync is an open-source project, and contributions are welcome! If you're interested in contributing, please check out our contribution guidelines.

+

License

+

ssh-sync is released under the MIT License.