Bunch of renaming and comment updates

Author: r-n-o

src/Cargo.lock

@@ -10,7 +10,7 @@ use qos_core::{
 	io::{SocketAddress, TimeVal},
 	server::{RequestProcessor, SocketServer},
 };
-use qos_net::remote_stream::RemoteStream;
+use qos_net::proxy_stream::ProxyStream;
 use rustls::RootCertStore;
 
 struct Processor {
@@ -31,7 +31,7 @@ impl RequestProcessor for Processor {
 		match msg {
 			PivotRemoteTlsMsg::RemoteTlsRequest { host, path } => {
 				let timeout = TimeVal::new(1, 0);
-				let mut stream = RemoteStream::new_by_name(
+				let mut stream = ProxyStream::connect_by_name(
 					&self.net_proxy,
 					timeout,
 					host.clone(),
@@ -61,12 +61,10 @@ impl RequestProcessor for Processor {
 				let http_request = format!(
 					"GET {path} HTTP/1.1\r\nHost: {host}\r\nConnection: close\r\n\r\n"
 				);
-				println!("=== making HTTP request: \n{http_request}");
 
 				tls.write_all(http_request.as_bytes()).unwrap();
-				let ciphersuite = tls.conn.negotiated_cipher_suite().unwrap();
+				let _ciphersuite = tls.conn.negotiated_cipher_suite().unwrap();
 
-				println!("=== current ciphersuite: {:?}", ciphersuite.suite());
 				let mut response_bytes = Vec::new();
 				let read_to_end_result: usize =
 					tls.read_to_end(&mut response_bytes).unwrap();
@@ -90,8 +88,8 @@ impl RequestProcessor for Processor {
 
 fn main() {
 	// Parse args:
-	// - first argument is the socket to bind to (server)
-	// - second argument is the socket to query (net proxy)
+	// - first argument is the socket to bind to (normal server server)
+	// - second argument is the socket to use for remote proxying
 	let args: Vec<String> = std::env::args().collect();
 
 	let socket_path: &String = &args[1];

src/integration/src/bin/pivot_remote_tls.rs

@@ -20,8 +20,6 @@ aws-nitro-enclaves-nsm-api = { version = "0.3", default-features = false }
 serde_bytes = { version = "0.11", default-features = false }
 serde = { version = "1", features = ["derive"], default-features = false }
 
-hickory-resolver = { version = "0.24.1", features = ["tokio-runtime"], default-features = false, optional = true}
-rand = { version = "0.8.5", default-features = false, optional = true }
 [dev-dependencies]
 qos_test_primitives = { path = "../qos_test_primitives" }
 qos_p256 = { path = "../qos_p256", features = ["mock"] }

src/qos_core/Cargo.toml

@@ -201,7 +201,7 @@ impl Stream {
 						&mut buf[received_bytes..len],
 						MsgFlags::empty(),
 					) {
-						Ok(size) if size == 0 => {
+						Ok(0) => {
 							return Err(IOError::RecvConnectionClosed);
 						}
 						Ok(size) => size,
@@ -234,7 +234,7 @@ impl Stream {
 					&mut buf[received_bytes..length],
 					MsgFlags::empty(),
 				) {
-					Ok(size) if size == 0 => {
+					Ok(0) => {
 						return Err(IOError::RecvConnectionClosed);
 					}
 					Ok(size) => size,
@@ -257,7 +257,7 @@ impl Stream {
 impl Read for Stream {
 	fn read(&mut self, buf: &mut [u8]) -> Result<usize, std::io::Error> {
 		match recv(self.fd, buf, MsgFlags::empty()) {
-			Ok(size) if size == 0 => Err(std::io::Error::new(
+			Ok(0) => Err(std::io::Error::new(
 				ErrorKind::ConnectionAborted,
 				"read 0 bytes",
 			)),
@@ -270,7 +270,7 @@ impl Read for Stream {
 impl Write for Stream {
 	fn write(&mut self, buf: &[u8]) -> Result<usize, std::io::Error> {
 		match send(self.fd, buf, MsgFlags::empty()) {
-			Ok(size) if size == 0 => Err(std::io::Error::new(
+			Ok(0) => Err(std::io::Error::new(
 				ErrorKind::ConnectionAborted,
 				"wrote 0 bytes",
 			)),
@@ -398,8 +398,10 @@ mod test {
 		assert_eq!(data, resp);
 	}
 
+	// TODO: replace this test with something simpler. Local socket which does a
+	// simple echo?
 	#[test]
-	fn stream_implement_reader_writer_interfaces() {
+	fn stream_implement_read_write_traits() {
 		let host = "api.turnkey.com";
 		let path = "/health";
 

src/qos_core/src/io/stream.rs

@@ -1,6 +1,4 @@
 //! Quorum protocol error
-use std::net::AddrParseError;
-
 use borsh::{BorshDeserialize, BorshSerialize};
 use qos_p256::P256Error;
 
@@ -143,8 +141,6 @@ pub enum ProtocolError {
 	/// The new manifest was different from the old manifest when we expected
 	/// them to be the same because they have the same nonce
 	DifferentManifest,
-	/// Parsing error with a protocol message component
-	ParseError(String),
 }
 
 impl From<std::io::Error> for ProtocolError {
@@ -188,10 +184,3 @@ impl From<qos_nsm::nitro::AttestError> for ProtocolError {
 		Self::QosAttestError(msg)
 	}
 }
-
-impl From<AddrParseError> for ProtocolError {
-	fn from(err: AddrParseError) -> Self {
-		let msg = format!("{err:?}");
-		Self::ParseError(msg)
-	}
-}

src/qos_core/src/protocol/error.rs

@@ -138,55 +138,6 @@ pub enum ProtocolMsg {
 		/// if the manifest envelope does not exist.
 		manifest_envelope: Box<Option<ManifestEnvelope>>,
 	},
-
-	/// Request from the enclave app to open a TCP connection to a remote host
-	/// This results in a new remote connection saved in protocol state
-	RemoteOpenRequest {
-		/// The hostname to connect to, e.g. "www.googleapis.com"
-		hostname: String,
-		/// e.g. 443
-		port: u16,
-		/// An array of DNS resolvers e.g. ["8.8.8.8", "8.8.4.4"]
-		dns_resolvers: Vec<String>,
-		/// Port number to perform DNS resolution, e.g. 53
-		dns_port: u16,
-	},
-	/// Response for `OpenTcpConnectionRequest`
-	RemoteOpenResponse {
-		/// Connection ID to reference the opened connection when used with
-		/// `RemoteRequest` and `RemoteResponse`. TODO: maybe we reply with a
-		/// fd name directly? Not sure what this ID will map to.
-		connection_id: u32,
-	},
-	/// Read from a remote connection
-	RemoteReadRequest {
-		/// A connection ID from `RemoteOpenResponse`
-		connection_id: u32,
-		/// number of bytes to read
-		size: usize,
-	},
-	/// Response to `RemoteReadRequest` containing read data
-	RemoteReadResponse {
-		/// A connection ID from `RemoteOpenResponse`
-		connection_id: u32,
-		/// number of bytes read
-		data: Vec<u8>,
-	},
-	/// Write to a remote connection
-	RemoteWriteRequest {
-		/// A connection ID from `RemoteOpenResponse`
-		connection_id: u32,
-		/// Data to be sent
-		data: Vec<u8>,
-	},
-	/// Response to `RemoteWriteRequest` containing the number of successfully
-	/// written bytes.
-	RemoteWriteResponse {
-		/// Connection ID from `RemoteOpenResponse`
-		connection_id: u32,
-		/// Number of bytes written successfully
-		size: usize,
-	},
 }
 
 #[cfg(test)]

src/qos_core/src/protocol/msg.rs

@@ -1,8 +1,13 @@
 # QOS Net
 
-This crate contains a proxy server which implements the protocol messages to implement remote connections:
-* `ProtocolMsg::RemoteOpenConnection`
-* `ProtocolMsg::RemoteRead`
-* `ProtocolMsg::RemoteWrite`
+This crate contains a proxy server and utilities to work with it. This server is a socket proxy: it listens on a socket (USOCK or VSOCK) and opens TCP connections to the outside. By sending `Proxy::*` messages over the socket, clients of the proxy can read/write/flush the TCP connections.
 
-It also contains a protocol and libraries to interact with the protocol
+When the proxy is run outside of an enclave and listening on a VSOCK port, the enclave process running on the inside can thus communicate with the outside and execute any protocol on top of a TCP connection by:
+* Opening a connection to a target hostname (`Proxy::ConnectByName`) or IP (`ProxyMsg::ConnectByIp`): this returns a connection ID for subsequent messages.
+* Sending `ProxyMsg::Read`, `ProxyMsg::Write` or `ProxyMsg::Flush` using the connection ID
+
+Libraries like [`rustls`](https://github.com/rustls/rustls) are built generically to let users run the TLS protocol over any struct which implements [`Read`](https://doc.rust-lang.org/std/io/trait.Read.html) and [`Write`](https://doc.rust-lang.org/std/io/trait.Write.html) traits.
+
+These traits are implemented in the `ProxyStream` struct: its `read`, `write`, and `flush` methods send `ProxyMsg` to a socket instead of manipulating a local socket or file descriptor.
+
+Binaries running in enclaves can thus open connections to the outside world by importing and using `ProxyStream`. See the following integration test: [src/integration/tests/remote_tls.rs](../integration/tests/remote_tls.rs).

src/qos_net/README.MD

@@ -8,7 +8,7 @@ use qos_core::{
 	server::SocketServer,
 };
 
-use crate::processor::Processor;
+use crate::proxy::Proxy;
 
 /// "cid"
 pub const CID: &str = "cid";
@@ -68,7 +68,7 @@ impl CLI {
 		} else if opts.parsed.help() {
 			println!("{}", opts.parsed.info());
 		} else {
-			SocketServer::listen(opts.addr(), Processor::new()).unwrap();
+			SocketServer::listen(opts.addr(), Proxy::new()).unwrap();
 		}
 	}
 }

src/qos_net/src/cli.rs

@@ -1,12 +1,12 @@
-//! Remote protocol error
+//! qos_net errors related to creating and using proxy connections.
 use std::net::AddrParseError;
 
 use borsh::{BorshDeserialize, BorshSerialize};
 use hickory_resolver::error::ResolveError;
 
-/// Errors during protocol execution.
+/// Errors related to creating and using proxy connections
 #[derive(Debug, Clone, PartialEq, Eq, BorshSerialize, BorshDeserialize)]
-pub enum ProtocolError {
+pub enum QosNetError {
 	/// Error variant encapsulating OS IO errors
 	IOError,
 	/// Error variant encapsulating OS IO errors
@@ -25,38 +25,38 @@ pub enum ProtocolError {
 	/// Attempt to save a connection with a duplicate ID
 	DuplicateConnectionId(u32),
 	/// Attempt to send a message to a remote connection, but ID isn't found
-	RemoteConnectionIdNotFound(u32),
+	ConnectionIdNotFound(u32),
 	/// Attempting to read on a closed remote connection (`.read` returned 0
 	/// bytes)
-	RemoteConnectionClosed,
-	/// Happens if a RemoteRead response has empty data
-	RemoteReadEmpty,
-	/// Happens if a RemoteRead returns too much data for the provided buffer
-	/// and the data doesn't fit. The first `usize` is the size of the received
-	/// data, the second `usize` is the size of the buffer.
-	RemoteReadOverflow(usize, usize),
+	ConnectionClosed,
+	/// Happens when a socket `read` results in no data
+	EmptyRead,
+	/// Happens when a socket `read` returns too much data for the provided
+	/// buffer and the data doesn't fit. The first `usize` is the size of the
+	/// received data, the second `usize` is the size of the buffer.
+	ReadOverflow(usize, usize),
 }
 
-impl From<std::io::Error> for ProtocolError {
+impl From<std::io::Error> for QosNetError {
 	fn from(_err: std::io::Error) -> Self {
 		Self::IOError
 	}
 }
 
-impl From<qos_core::io::IOError> for ProtocolError {
+impl From<qos_core::io::IOError> for QosNetError {
 	fn from(_err: qos_core::io::IOError) -> Self {
 		Self::QOSIOError
 	}
 }
 
-impl From<AddrParseError> for ProtocolError {
+impl From<AddrParseError> for QosNetError {
 	fn from(err: AddrParseError) -> Self {
 		let msg = format!("{err:?}");
 		Self::ParseError(msg)
 	}
 }
 
-impl From<ResolveError> for ProtocolError {
+impl From<ResolveError> for QosNetError {
 	fn from(err: ResolveError) -> Self {
 		let msg = format!("{err:?}");
 		Self::ParseError(msg)

src/qos_net/src/error.rs

@@ -1,9 +1,10 @@
-//! This crate contains a simple proxy server to implement QOS protocol messages
-//! related to establishing and using remote connections.
+//! This crate contains a simple proxy server which binds to a local socket and
+//! opens TCP connection It exposes a simple protocol for remote clients who
+//! connect to let them manipulate these connections (read/write/flush)
 
 #![deny(clippy::all, unsafe_code)]
 pub mod cli;
 pub mod error;
-pub mod processor;
-pub mod remote_connection;
-pub mod remote_stream;
+pub mod proxy;
+pub mod proxy_connection;
+pub mod proxy_stream;