[p2p] Polish (#20)

* add badges

* working on security.md

* update security

* update security

* setup READMEs

* describe p2p

* add all explanations

* first stab at description

* write features

* document ed25519

* add status to rust docs

* add network definitions

* describe oracle

* add note about ping/pongs

* define Sender

* finish channel definitions

* nits

* update version

* lint last

Author: patrick-ogrady

Cargo.lock

@@ -1,5 +1,18 @@
-# monorepo
+# commonware 
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE-MIT)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE-APACHE)
+[![Rust](https://github.com/commonwarexyz/monorepo/actions/workflows/rust.yml/badge.svg)](https://github.com/commonwarexyz/monorepo/actions/workflows/rust.yml)
+
+## Primitives 
+
+* [p2p](./p2p/README.md): Communicate with authenticated peers over encrypted connections. 
+
+## Examples
+
+_This directory contains examples of how to use various crates in this repository. The code in these examples is often insecure and is not intended to be used in production._
+
+* [chat](./examples/chat/README.md): Send encrypted messages to a group of friends using [commonware-p2p](https://crates.io/crates/commonware-p2p). 
 
 ## Licensing
 

README.md

@@ -0,0 +1,11 @@
+# Reporting Security Issues
+
+We welcome security disclosures and are committed to providing prompt attention to any confirmed security issues.
+
+Vulnerabilities should be reported privately [via GitHub Security](https://github.com/commonwarexyz/monorepo/security) instead of as a public issue.
+
+We do not yet offer a bounty program for responsible disclosure of security vulnerabilities, however, we do track contributions and record them on the leaderboard below.
+
+# Leaderboard
+
+1. (Your Name Here)

SECURITY.md

@@ -4,7 +4,7 @@ edition = "2021"
 publish = true
 version = "0.0.4"
 license = "MIT OR Apache-2.0"
-description = "chat using commonware-p2p"
+description = "Send encrypted messages to a group of friends using commonware-p2p."
 readme = "README.md"
 homepage = "https://commonware.xyz"
 repository = "https://github.com/commonwarexyz/monorepo"

examples/README.md

@@ -1,5 +1,37 @@
-# chat 
+# commonware-chat 
+
+[![Crates.io](https://img.shields.io/crates/v/commonware-chat.svg)](https://crates.io/crates/commonware-chat)
+
+Send encrypted messages to a group of friends using [commonware-p2p](https://crates.io/crates/commonware-p2p).
+
+## Usage
+
+### Person 1 (Bootstrapper)
+
+```
+cargo run -- --me=1@3001 --allowed_keys=1,2,3,4
+```
+
+### Person 2
+
+```
+cargo run -- --me=2@3002 --allowed_keys=1,2,3,4 [email protected]:3001 
+```
+
+### Person 3
+
+```
+cargo run -- --me=3@3003 --allowed_keys=1,2,3,4 [email protected]:3001 
+```
+
+### Person 4 (Different Bootstrapper)
+
+```
+cargo run -- --me=4@3004 --allowed_keys=1,2,3,4 [email protected]:3003
+```
+
+### Person 5 (Blocked)
 
 ```
-cargo run -- --me=1@3000 --allowed_keys=1,2,3,4 --bootstrappers=2@127.0.0.1:3090 
+cargo run -- --me=5@3005 --allowed_keys=1,2,3,4,5 --bootstrappers=1@127.0.0.1:3001 
 ```

examples/chat/Cargo.toml

@@ -1,3 +1,5 @@
+//! Send encrypted messages to a group of friends using [commonware-p2p](https://crates.io/crates/commonware-p2p).
+
 use clap::{value_parser, Arg, Command};
 use commonware_p2p::{
     crypto::{self, Crypto},

examples/chat/README.md

@@ -2,9 +2,9 @@
 name = "commonware-p2p"
 edition = "2021"
 publish = true
-version = "0.0.4"
+version = "0.0.5"
 license = "MIT OR Apache-2.0"
-description = "p2p for blockchains"
+description = "Communicate with authenticated peers over encrypted connections."
 readme = "README.md"
 homepage = "https://commonware.xyz"
 repository = "https://github.com/commonwarexyz/monorepo"

examples/chat/src/main.rs

@@ -1,32 +1,9 @@
-# p2p
+# commonware-p2p
 
-## Disclaimer
+[![Crates.io](https://img.shields.io/crates/v/commonware-p2p.svg)](https://crates.io/crates/commonware-p2p)
 
-`p2p` is **ALPHA** software and is not yet recommended for production use. Developers should expect breaking changes and occasional instability.
+Communicate with authenticated peers over encrypted connections.
 
-## Features
+## Status 
 
-* no TLS
-* chacha20-poly1305 encryption
-* native message chunking
-* arbitrary crypto identities
-* peer discovery using ordered bit vectors
-* fully-connected peers
-* configurable rate limiting for each message type
-* metrics via prometheus
-* message prioritization across channels
-* multi-plexing over a single connection
-
-## Components 
-
-### Dialer
-
-### Listener
-
-### Tracker
-
-### Spawner
-
-### Peer
-
-### Router
+`commonware-p2p` is **ALPHA** software and is not yet recommended for production use. Developers should expect breaking changes and occasional instability.

p2p/Cargo.toml

@@ -97,6 +97,10 @@ impl Mailbox {
     }
 }
 
+/// Mechanism to register authorized peers.
+///
+/// Peers that are not explicitly authorized
+/// will be blocked by commonware-p2p.
 #[derive(Clone)]
 pub struct Oracle {
     sender: mpsc::Sender<Message>,
@@ -107,6 +111,17 @@ impl Oracle {
         Self { sender }
     }
 
+    /// Register a set of authorized peers at a given index.
+    ///
+    /// These peer sets are used to construct a bit vector (sorted by public key)
+    /// to share knowledge about dialable IPs. If a peer does not yet have an index
+    /// associated with a bit vector, the discovery message will be dropped.
+    ///
+    /// # Parameters
+    ///
+    /// * `index` - Index of the set of authorized peers (like a blockchain height).
+    ///   Should be monotonically increasing.
+    /// * `peers` - Vector of authorized peers at an `index` (does not need to be sorted).
     pub async fn register(&self, index: u64, peers: Vec<PublicKey>) {
         let _ = self.sender.send(Message::Register { index, peers }).await;
     }

p2p/README.md

@@ -4,6 +4,16 @@ use governor::Quota;
 use std::collections::HashMap;
 use tokio::sync::mpsc;
 
+/// Tuple representing a message received from a given public key.
+///
+/// This message is guranteed to adhere to the configuration of the channel and
+/// will already be decrypted and authenticated.
+pub type Message = (PublicKey, Bytes);
+/// Channel to asynchronously receive messages from a channel.
+pub type Receiver = mpsc::Receiver<Message>;
+
+/// Sender is the mechanism used to send arbitrary bytes to
+/// a set of recipients over a pre-defined channel.
 pub struct Sender {
     channel: u32,
     messenger: Messenger,
@@ -14,17 +24,21 @@ impl Sender {
         Self { channel, messenger }
     }
 
-    /// priority is over all messages across all channels
+    /// Sends a message to a set of recipients.
+    ///
+    /// # Parameters
+    ///
+    /// * `recipients` - The set of recipients to send the message to.
+    /// * `message` - The message to send.
+    /// * `priority` - Whether the message should be sent with priority (across
+    ///   all channels).
     pub async fn send(&self, recipients: Vec<PublicKey>, message: Bytes, priority: bool) {
         self.messenger
             .content(recipients, self.channel, message, priority)
             .await;
     }
 }
 
-pub type Message = (PublicKey, Bytes);
-pub type Receiver = mpsc::Receiver<Message>;
-
 #[derive(Clone)]
 pub struct Channels {
     messenger: Messenger,
@@ -39,7 +53,6 @@ impl Channels {
         }
     }
 
-    /// messages can span multiple frames
     pub fn register(
         &mut self,
         channel: u32,

p2p/src/actors/tracker/ingress.rs

@@ -1,10 +1,15 @@
+//! Ed25519 implementation of the Crypto trait.
+
 use crate::crypto;
 use ed25519_dalek::{
     Signature, Signer, SigningKey, Verifier, VerifyingKey, PUBLIC_KEY_LENGTH, SECRET_KEY_LENGTH,
     SIGNATURE_LENGTH,
 };
 use sha2::{Digest, Sha256};
 
+const MESSAGE_PREFIX: &str = "commonware-p2p";
+
+/// Ed25519 Signer.
 #[derive(Clone)]
 pub struct Ed25519 {
     signer: SigningKey,
@@ -19,6 +24,12 @@ impl Ed25519 {
             verifier: verifier.to_bytes().to_vec().into(),
         }
     }
+
+    fn payload(message: Vec<u8>) -> Vec<u8> {
+        let mut payload = Vec::from(MESSAGE_PREFIX.as_bytes());
+        payload.extend_from_slice(&message);
+        payload
+    }
 }
 
 impl crypto::Crypto for Ed25519 {
@@ -27,7 +38,8 @@ impl crypto::Crypto for Ed25519 {
     }
 
     fn sign(&mut self, message: Vec<u8>) -> crypto::Signature {
-        self.signer.sign(&message).to_bytes().to_vec().into()
+        let payload = Self::payload(message);
+        self.signer.sign(&payload).to_bytes().to_vec().into()
     }
 
     fn validate(public_key: &crypto::PublicKey) -> bool {
@@ -56,11 +68,19 @@ impl crypto::Crypto for Ed25519 {
             Err(_) => return false,
         };
         let signature = Signature::from(signature);
-        public_key.verify(&message, &signature).is_ok()
+        let payload = Self::payload(message);
+        public_key.verify(&payload, &signature).is_ok()
     }
 }
 
-pub fn insecure_signer(peer: u16) -> Ed25519 {
-    let secret_key: [u8; SECRET_KEY_LENGTH] = Sha256::digest(peer.to_be_bytes()).into();
+/// Creates a new Ed25519 signer with a secret key derived from the provided
+/// seed.
+///
+/// # Warning
+///
+/// This function is intended for testing and demonstration purposes only.
+/// It should never be used in production.
+pub fn insecure_signer(seed: u16) -> Ed25519 {
+    let secret_key: [u8; SECRET_KEY_LENGTH] = Sha256::digest(seed.to_be_bytes()).into();
     Ed25519::new(SigningKey::from(secret_key))
 }

p2p/src/channels.rs

@@ -1,16 +1,29 @@
-//! TODO
+//! Cryptographic definitions required by commonware-p2p and select implementations
+//! of different PKI schemes.
 
 use bytes::Bytes;
 
 pub mod ed25519;
 
+/// Byte array representing an arbitrary public key.
 pub type PublicKey = Bytes;
+/// Byte array representing an arbitrary signature.
 pub type Signature = Bytes;
 
+/// Cryptographic operations required by commonware-p2p.
+///
+/// # Warning
+///
+/// Although data provided to this implementation to be signed are expected to be
+/// unique to commonware-p2p, it is strongly recommended to prefix any payloads
+/// with a unique identifier to prevent replay attacks.
 pub trait Crypto: Send + Sync + Clone + 'static {
+    /// Returns the public key of the signer.
     fn me(&self) -> PublicKey;
+    /// Sign the given data (usually an IP).
     fn sign(&mut self, data: Vec<u8>) -> Signature;
-
+    /// Verify that a public key is well-formatted.
     fn validate(public_key: &PublicKey) -> bool;
+    /// Check that a signature is valid for the given data and public key.
     fn verify(data: Vec<u8>, public_key: &PublicKey, signature: &Signature) -> bool;
 }

p2p/src/crypto/ed25519.rs

@@ -1,6 +1,29 @@
-//! Fully-connected ...
+//! Communicate with authenticated peers over encrypted connections.
 //!
-//! TODO: Add more documentation here
+//! commonware-p2p provides encrypted, multiplexed communication between fully-connected peers
+//! identified by a developer-specified cryptographic identity (i.e. BLS, ed25519, etc.). Unlike
+//! most p2p crates, commonware-p2p implements its own encrypted transport layer (no TLS) that
+//! exclusively uses said cryptographic identities to authenticate incoming connections (dropping
+//! any that aren't explicitly authorized). Peer discovery occurs automatically using ordered bit
+//! vectors (sorted by authorized cryptographic identities) to efficiently communicate knowledge
+//! of dialable peers.
+//!
+//! # Status
+//!
+//! `commonware-p2p` is **ALPHA** software and is not yet recommended for production use. Developers should
+//! expect breaking changes and occasional instability.
+//!
+//! # Features
+//!
+//! * No TLS, No X.509 Certificates, No Protocol Negotiation
+//! * ChaCha20-Poly1305 Stream Encryption
+//! * Arbitrary Cryptographic Peer Identities
+//! * Automatic Peer Discovery Using Bit Vectors (Used as Ping/Pongs)
+//! * Multiplexing With Configurable Rate Limiting Per Channel and Send Prioritization
+//! * Emebdded Message Chunking
+//! * Metrics via Prometheus
+//!
+//! # Example
 //!
 //! ```rust
 //! use commonware_p2p::{