Merge pull request #72 from nyonson/update-docs

Update docs

README.md

@@ -1,5 +1,18 @@
 # BIP324 Encrypted Transport Protocol
 
-[BIP324](https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki) describes an encrypted communication protocol over the Bitcoin P2P network. Encrypted messages offer a number of benefits over plaintext communication, even though the data exchanged over the Bitcoin P2P network is public to some degree. For instance, plaintext message tampering without detection is trivial for a man in the middle (MitM) attacker. Additionally, a nefarious actor may associate metadata such as IP addresses and transaction origins without explicitly having to connect directly to peers. BIP 324 - "V2" - transport forces nefarious observers to actively connect to peers as opposed to passively observing network traffic, and makes packet tampering detectable. Furthermore, V2 messages over TCP/IP look no different from random noise, making Bitcoin P2P packets indistinguishable from other network packets. 
+[BIP324](https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki) describes the V2 encrypted communication protocol for the bitcoin P2P network. 
 
-The `protocol` package export the `BIP324` library. The `proxy` package is a small application to enable V2 for V1-only clients.
+## Motivation
+
+Bitcoin's original P2P protocol, "V1", was designed without any encryption. Even though the data exchanged over the bitcoin P2P network is public to some degree, encrypted communications offers a number of benefits over plaintext communication. 
+
+* Internet Service Providers (ISPs) can easily detect and censor plaintext bitcoin communication.  
+* Plaintext message tampering, without detection, is trivial for a man in the middle (MitM) attacker. 
+* Nefarious actors may associate metadata, such as IP addresses and transaction origins, without explicitly having to connect directly to peers.
+
+BIP 324 - "V2" - encrypted communication protects against the above issues increasing the privacy and censorship-resistance of the bitcoin ecosystem. Any applications communicating with bitcoin nodes, including light clients, should make use of the V2 protocol.
+
+## Packages
+
+* `protocol` - Exports the `BIP324` client library.
+* `proxy` - A small side-car application to enable V2 communication for V1-only applications.

protocol/README.md

@@ -1,19 +1,27 @@
 # Protocol
 
-Alice and Bob initiate a connection by sending three messages to each other to derive a number of shared secrets. Alice begins the connection by deriving a public/private keypair over `secp256k1`, the typical Bitcoin curve. Alice is known as the *initiator*. She encodes the public key in the [Elligator Swift](https://eprint.iacr.org/2022/759.pdf) format (64-bytes), optionally pads it with some random garbage bytes, and sends the message to Bob. Bob, known as the *responder*, decodes the Elligator Swift public key, and derives an ephemeral public/private keypair himself. Using his public and private keys, as well as Alice's public key, Bob performs a variation of the Elliptic Curve Diffie Hellman algorithm to derive a shared key. From this shared key, Bob derives multiple keys and a session ID using the HKDF algorithm. Next, Bob creates garbage data, and sends his public key, garbage data, an encrypted packet using the garbage data, and a version negotiation to Alice. With Bob's public key, Alice derives the shared secret and ensures the decrypted packet is authenticated with the garbage Bob sent her. Finally, Alice sends a "garbage terminator" and an encrypted packet using her garbage data, so Bob may authenticate she derived the correct secret and he can decode her messages. Alice and Bob may now freely exchange encrypted messages over the Bitcoin P2P protocol.
+A BIP324 library to establish and communicate over an encrypted channel.
 
-## Interface
+The library is designed with a bare `no_std` and "Sans I/O" interface to keep it as agnostic as possible to application runtimes, but higher level interfaces are exposed for ease of use.
 
-The library exposes two core structures, the `Handshake` and the `PacketHandler`. The handshake is used to generate a packet handler and performs the one-and-a-half roundtrips dance between the peers described above. A successful handshake results in a packet handler which performs the encrypt and decrypt operations for the channel.
+The `async` feature includes the high-level `AsyncProcotol` type which helps create and manage an encrypted channel. 
 
-Both structures are designed with a bare `no_std` and "Sans I/O" interface to keep them as agnostic as possible to application runtimes. 
+The lower-level `Handshake` and `PacketHandler` types can be directly used by applications which require more control. The handshake performs the one-and-a-half round trip dance between the peers in order to generate secret materials. A successful handshake results in a packet handler which performs the encrypt and decrypt operations for the lifetime of the channel.
 
 ## Feature Flags
 
 * `alloc` -- Expose memory allocation dependent features.
 * `std`   -- Includes the `alloc` memory allocation feature as well as extra standard library dependencies for I/O and random number generators.
 * `async` -- High level wrappers for asynchronous read and write runtimes.
 
+## Handshake
+
+Alice and Bob initiate a connection by sending three messages to each other to derive a number of shared secrets. Alice begins the connection by deriving a public/private keypair over `secp256k1`, the typical bitcoin curve. Alice is known as the *initiator*. She encodes the public key in the [Elligator Swift](https://eprint.iacr.org/2022/759.pdf) format (64-bytes), optionally pads it with some random garbage bytes, and sends the message to Bob. 
+
+Bob, known as the *responder*, decodes the Elligator Swift public key, and derives an ephemeral public/private keypair himself. Using his public and private keys, as well as Alice's public key, Bob performs a variation of the Elliptic Curve Diffie Hellman algorithm to derive a shared key. From this shared key, Bob derives multiple keys and a session ID using the HKDF algorithm. Next, Bob creates garbage data, and sends his public key, garbage data, an encrypted packet using the garbage data, and a version negotiation to Alice.
+
+With Bob's public key, Alice derives the shared secret and ensures the decrypted packet is authenticated with the garbage Bob sent her. Finally, Alice sends a "garbage terminator" and an encrypted packet using her garbage data, so Bob may authenticate she derived the correct secret and he can decode her messages. Alice and Bob may now freely exchange encrypted messages over the bitcoin V2 P2P protocol.
+
 ## ChaCha20Poly1305
 
 BIP324 elects to use the ChaCha20Poly1305 Authenticated Encryption with Addition Data (AEAD) algorithm under the hood. This is a combination of the ChaCha20 stream cipher and the Poly1305 message authentication code (MAC). In this context, "authentication" refers to the encrypted message's integrity, not to the identity of either party communicating.