Merge pull request #85 from flashbots/peg/doccomments

Improve doccomments for publishing as library

Author: ameba23

Cargo.lock

@@ -3,9 +3,12 @@ members = [".", "dummy-attestation-server"]
 
 [package]
 name = "attested-tls-proxy"
-version = "0.1.0"
+version = "0.0.1"
 edition = "2024"
 license = "MIT"
+description = "An HTTP attested TLS proxy server and client for secure communication with CVM services"
+repository = "https://github.com/flashbots/attested-tls-proxy"
+keywords = ["attested-TLS", "CVM", "TDX"]
 
 [dependencies]
 tokio = { version = "1.48.0", features = ["full"] }

Cargo.toml

@@ -4,6 +4,7 @@ version = "0.1.0"
 edition = "2024"
 license = "MIT"
 publish = false
+repository = "https://github.com/flashbots/attested-tls-proxy"
 
 [dependencies]
 attested-tls-proxy = { path = ".." }

dummy-attestation-server/Cargo.toml

@@ -1,4 +1,4 @@
-//! Microsoft Azure Attestation (MAA) evidence generation and verification
+//! Microsoft Azure vTPM attestation evidence generation and verification
 mod ak_certificate;
 mod nv_index;
 use ak_certificate::{read_ak_certificate_from_tpm, verify_ak_cert_with_azure_roots};
@@ -245,6 +245,7 @@ impl RsaPubKey {
     }
 }
 
+/// An error when generating or verifying a Microsoft Azure vTPM attestation
 #[derive(Error, Debug)]
 pub enum MaaError {
     #[error("Report: {0}")]

src/attestation/azure/mod.rs

@@ -1,3 +1,5 @@
+//! CVM attestation generation and verification
+
 #[cfg(feature = "azure")]
 pub mod azure;
 pub mod dcap;
@@ -122,23 +124,7 @@ pub struct AttestationGenerator {
 }
 
 impl AttestationGenerator {
-    /// Create an [AttestationGenerator] detecting the attestation type if it is specified as 'auto'
-    pub async fn new_with_detection(
-        attestation_type_string: Option<String>,
-        dummy_dcap_url: Option<String>,
-    ) -> Result<Self, AttestationError> {
-        let attestation_type_string = attestation_type_string.unwrap_or_else(|| "auto".to_string());
-        let attestaton_type = if attestation_type_string == "auto" {
-            tracing::info!("Doing attestation type detection...");
-            AttestationType::detect().await?
-        } else {
-            serde_json::from_value(serde_json::Value::String(attestation_type_string))?
-        };
-        tracing::info!("Local platform: {attestaton_type}");
-
-        Self::new(attestaton_type, dummy_dcap_url)
-    }
-
+    /// Create an attesation generator with given attestation type
     pub fn new(
         attestation_type: AttestationType,
         dummy_dcap_url: Option<String>,
@@ -149,13 +135,37 @@ impl AttestationGenerator {
         }
     }
 
+    /// Detect what confidential compute platform is present and create the approprate attestation
+    /// generator
+    pub async fn detect() -> Result<Self, AttestationError> {
+        Self::new_with_detection(None, None).await
+    }
+
+    /// Do not generate attestations
     pub fn with_no_attestation() -> Self {
         Self {
             attestation_type: AttestationType::None,
             dummy_dcap_url: None,
         }
     }
 
+    /// Create an [AttestationGenerator] detecting the attestation type if it is not given
+    pub async fn new_with_detection(
+        attestation_type_string: Option<String>,
+        dummy_dcap_url: Option<String>,
+    ) -> Result<Self, AttestationError> {
+        let attestation_type_string = attestation_type_string.unwrap_or_else(|| "auto".to_string());
+        let attestaton_type = if attestation_type_string == "auto" {
+            tracing::info!("Doing attestation type detection...");
+            AttestationType::detect().await?
+        } else {
+            serde_json::from_value(serde_json::Value::String(attestation_type_string))?
+        };
+        tracing::info!("Local platform: {attestaton_type}");
+
+        Self::new(attestaton_type, dummy_dcap_url)
+    }
+
     /// Create an [AttestationGenerator] without a given dummy DCAP url - meaning Dummy attestation
     /// type will not be possible
     pub fn new_not_dummy(attestation_type: AttestationType) -> Result<Self, AttestationError> {
@@ -190,7 +200,7 @@ impl AttestationGenerator {
         }
     }
 
-    /// Generate an attestation exchange message
+    /// Generate an attestation exchange message with given input data
     pub async fn generate_attestation(
         &self,
         input_data: [u8; 64],
@@ -201,7 +211,7 @@ impl AttestationGenerator {
         })
     }
 
-    /// Generate attestation evidence bytes based on attestation type
+    /// Generate attestation evidence bytes based on attestation type, with given input data
     async fn generate_attestation_bytes(
         &self,
         input_data: [u8; 64],

src/attestation/mod.rs

@@ -1,3 +1,4 @@
+//! A one-shot attested TLS proxy client which sends a single GET request and returns the response
 use crate::{AttestationGenerator, AttestationVerifier, ProxyClient, ProxyError};
 use tokio_rustls::rustls::pki_types::CertificateDer;
 

src/attested_get.rs

@@ -1,3 +1,4 @@
+//! Attested TLS protocol server and client
 use crate::{
     attestation::{
         measurements::MultiMeasurements, AttestationError, AttestationExchangeMessage,

src/attested_tls.rs

@@ -1,3 +1,4 @@
+//! Static HTTP file server provided by an attested TLS proxy server
 use crate::{AttestationGenerator, AttestationVerifier, ProxyError, ProxyServer, TlsCertAndKey};
 use std::{net::SocketAddr, path::PathBuf};
 use tokio::net::ToSocketAddrs;

src/file_server.rs

@@ -1,3 +1,4 @@
+//! Provides health / version details for an attested proxy server or client
 use axum::{routing::get, Json, Router};
 use serde::{Deserialize, Serialize};
 use std::net::SocketAddr;

src/health_check.rs

@@ -1,3 +1,4 @@
+//! An attested TLS protocol and HTTPS proxy
 pub mod attestation;
 pub mod attested_get;
 pub mod attested_tls;