Doccomments

Author: ameba23

src/attestation.rs

@@ -5,14 +5,19 @@ use x509_parser::prelude::*;
 
 /// Represents a CVM technology with quote generation and verification
 pub trait AttestationPlatform: Clone + Send + 'static {
+    /// Whether this is CVM attestation. This should always return true except for the [NoAttestation] case.
+    ///
+    /// When false, allows TLS client to be configured without client authentication
     fn is_cvm(&self) -> bool;
 
+    /// Generate an attestation
     fn create_attestation(
         &self,
         cert_chain: &[CertificateDer<'_>],
         exporter: [u8; 32],
     ) -> Result<Vec<u8>, AttestationError>;
 
+    /// Verify the given attestation payload
     fn verify_attestation(
         &self,
         input: Vec<u8>,
@@ -71,7 +76,7 @@ impl AttestationPlatform for NoAttestation {
         false
     }
 
-    /// Mocks creating an attestation
+    /// Create an empty attestation
     fn create_attestation(
         &self,
         _cert_chain: &[CertificateDer<'_>],
@@ -80,7 +85,7 @@ impl AttestationPlatform for NoAttestation {
         Ok(Vec::new())
     }
 
-    /// Mocks verifying an attestation
+    /// Ensure that an empty attestation is given
     fn verify_attestation(
         &self,
         input: Vec<u8>,

src/lib.rs

@@ -266,6 +266,9 @@ impl<L: AttestationPlatform, R: AttestationPlatform> ProxyClient<L, R> {
         .await
     }
 
+    /// Create a new proxy with given TLS configuration
+    ///
+    /// This is private as it allows dangerous configuration but is used in tests
     async fn new_with_tls_config(
         client_config: Arc<ClientConfig>,
         local: impl ToSocketAddrs,
@@ -293,6 +296,7 @@ impl<L: AttestationPlatform, R: AttestationPlatform> ProxyClient<L, R> {
         })
     }
 
+    /// Accept an incoming connection and handle it
     pub async fn accept(&self) -> io::Result<()> {
         let (inbound, _client_addr) = self.inner.listener.accept().await?;
 
@@ -322,10 +326,12 @@ impl<L: AttestationPlatform, R: AttestationPlatform> ProxyClient<L, R> {
         Ok(())
     }
 
+    /// Helper to return the local socket address from the underlying TCP listener
     pub fn local_addr(&self) -> std::io::Result<SocketAddr> {
         self.inner.listener.local_addr()
     }
 
+    /// Handle an incoming connection
     async fn handle_connection(
         inbound: TcpStream,
         connector: TlsConnector,
@@ -386,6 +392,7 @@ impl<L: AttestationPlatform, R: AttestationPlatform> ProxyClient<L, R> {
     }
 }
 
+/// An error when running a proxy client or server
 #[derive(Error, Debug)]
 pub enum ProxyError {
     #[error("Client auth is required when the client is running in a CVM")]
@@ -404,6 +411,7 @@ pub enum ProxyError {
     IntConversion(#[from] TryFromIntError),
 }
 
+/// Given a byte array, encode its length as a 4 byte big endian u32
 fn length_prefix(input: &[u8]) -> [u8; 4] {
     let len = input.len() as u32;
     len.to_be_bytes()

src/main.rs

@@ -19,8 +19,10 @@ struct Cli {
 enum CliCommand {
     /// Run a proxy client
     Client {
+        /// The socket address of the proxy server
         #[arg(short, long)]
         server_address: SocketAddr,
+        /// The domain name of the proxy server
         #[arg(long)]
         server_name: String,
         /// The path to a PEM encoded private key for client authentication
@@ -41,6 +43,8 @@ enum CliCommand {
         /// The path to a PEM encoded certificate chain
         #[arg(long)]
         cert_chain: PathBuf,
+        /// Whether to use client authentication. If the client is running in a CVM this must be
+        /// enabled.
         #[arg(long)]
         client_auth: bool,
     },
@@ -115,6 +119,7 @@ async fn main() -> anyhow::Result<()> {
     }
 }
 
+/// Load TLS details from storage
 fn load_tls_cert_and_key(
     cert_chain: PathBuf,
     private_key: PathBuf,