Update readme

README.md

@@ -1,30 +1,35 @@
-- https://github.com/mcginty/snow/tree/master/examples
-- https://github.com/black-binary/snowstorm/tree/master/examples
-- https://cryptoservices.github.io/cryptography/protocols/2016/04/27/noise-protocol.html
+# ruck
 
-- https://github.com/libp2p
+`ruck` is a command line tool used for hosting relay servers and sending end-to-end encrypted files between clients. It was heavily inspired by [croc](https://github.com/schollz/croc), one of the easiest ways to send files between peers. This document describes the protocol `ruck` uses to support this functionality.
 
-- https://docs.rs/spake2/latest/spake2/
-- https://crates.io/crates/chacha20poly1305
-- https://briansmith.org/rustdoc/ring/aead/index.html
-- https://libsodium.gitbook.io/doc/secret-key_cryptography/secretstream
+### Version
 
-- https://kerkour.com/rust-symmetric-encryption-aead-benchmark/
-- https://docs.rs/aes-gcm/latest/aes_gcm/
+This document refers to version `0.1.0` of `ruck` as defined by the `Cargo.toml` file.
 
-- https://github.com/rust-lang/flate2-rs
-- https://crates.io/crates/async-compression
+## Server
 
-- https://pdos.csail.mit.edu/papers/chord:sigcomm01/chord_sigcomm.pdf
-- https://pdos.csail.mit.edu/6.824/schedule.html
-- https://flylib.com/books/en/2.292.1.105/1/
-- https://en.wikipedia.org/wiki/Two_Generals%27_Problem
+The server in `ruck` exposes a TCP port.
+Its only functions are to staple connections and shuttle bytes between stapled connections.
+The first 32 bytes sent over the wire from a new client are used as its unique identifier.
+When a new client joins, if the server has another open connection with the same identifier, the connections are then stapled.
+The clients have some mechanism for agreeing on these identifiers, however, from the server's perspective it doesn't matter how they agree.
 
-- https://kobzol.github.io/rust/ci/2021/05/07/building-rust-binaries-in-ci-that-work-with-older-glibc.html
+Once the connection is stapled, all bytes are piped across until a client disconnects or times out.
+The time out is set to remove idle connections.
+The server does nothing else with the bytes, so the clients are free to end-to-end encrypt their messages.
+For this reason, updates to the `ruck` protocol do not typically necessitate server redeployments.
 
-## Todo
+## Client
 
-- [ ] Use tracing
-- [ ] Add progress bars
-- [ ] Exit happily when transfer is complete
-- [ ] Compress files
+There are two types of clients - `send` and `receive` clients.
+Out of band, the clients agree on a relay server and password, from which they can derive the 32 byte identifier used by the server to staple their connections.
+Clients have the option of using the single-use, automatically generated passwords which `ruck` supplies by default.
+Using the passwords per the [Spake2](https://docs.rs/spake2/0.3.1/spake2/) handshake algorithm, clients generate a symmetric key with which to encrypt their subsequent messages.
+Once the handshake is complete, `send` and `receive` negotiate and exchange files per the following:
+
+- `send` offers a list of files and waits.
+- `receive` specifies which bytes it wants from these files.
+- `send` sends the specified bytes and waits.
+- `receive` sends heartbeats with progress updates.
+- `send` hangs up once the heartbeats stop or received a successful heartbeat.
+- `receive` hangs up once the downloads are complete.

docs/Protocol.md

@@ -1,39 +0,0 @@
-# Protocol
-
-`ruck` is a command line tool used for hosting relay servers and sending end-to-end encrypted files between clients. This document describes the protocol `ruck` uses to support this functionality.
-
-### Version
-
-This document refers to version `0.1.0` of `ruck` as defined by the `Cargo.toml` file.
-
-## Server
-
-The server in `ruck` exposes a TCP port, typically port `8080`. Its only functions are to staple connections and shuttle bytes between stapled connections. The first 32 bytes sent from a new client are stored in a HashMap. If the same 32 bytes are already in the Hashmap, the connections are then stapled. This 32 byte key is defined by the [Spake2](https://docs.rs/spake2/0.3.1/spake2/) handshake algorithm which the clients employ to negotiate a single use password to encrypt all their messages. Although from the server's perspective, the clients can agree on these 32 bytes in any way.
-
-Once the connection is stapled, all bytes are piped across until a client disconnects or times out. The time out is set to remove idle connections. Beyond stapling connections, the file negotiation aspect of the protocol is managed by the clients. For this reason, `ruck` servers are very resistant to updates and protocol updates typically do not necessitate new deployments.
-
-The server does nothing else with the bytes, so the clients are free to end-to-end encrypt their messages, as long as the first 32 bytes sent over the wire match. Other than that, it is a private echo server.
-
-## Client
-
-There are two types of clients - `send` and `receive` clients. The following state machine describes the protocol. All the messages after the exchange of passwords are typically bzip compressed, encrypted with Aes256Gcm using a Spake2 key derived from the exchanged password. They are sent over the wire as bincode. Each message has a fixed size of 1024 \* 1024 bytes.
-
-Message Types:
-
-- Vec<File Info>
--
-
-- Set a timeout for new messages.
-
-Send or receive.
-
-If send:
-
-- Send message with file info
-
-They exchange passwords.
-Send offers a list of files.
-Receive specifies which bytes it wants from these files.
-Send sends the specified bytes and waits.
-Receive sends heartbeats with progress updates.
-Send hangs up once the heartbeats stop or received a successful heartbeat.