docs: improve challenge encoding and async TPM documentation

Enhanced documentation and warnings for better developer understanding.

Challenge encoding:
- Improved warning when challenge is not valid base64
- Show base64 decode error and challenge preview for debugging
- Clarify UTF-8 fallback is for testing/backwards compatibility

Async TPM operations:
- Document async/sync bridge pattern using spawn_blocking
- Explain runtime requirements (tokio runtime, blocking thread pool)
- Clarify why TPM operations need blocking threads (hardware I/O, sync API)
- Document error handling for both task panics and TPM failures

Assisted-by: Claude 4 Sonnet
Signed-off-by: Sergio Correia <[email protected]>

Author: sergio-correia

keylime/src/auth.rs

@@ -107,9 +107,57 @@ impl SessionToken {
     }
 }
 
-/// Mock TPM operations for testing
+/// TPM operations abstraction for authentication proof-of-possession
+///
+/// This trait provides an async interface for generating TPM-based cryptographic
+/// proofs during the authentication protocol. Implementations handle the details
+/// of interacting with TPM hardware or providing mock proofs for testing.
+///
+/// ## Async Design
+///
+/// The trait is async (`#[async_trait]`) even though underlying TPM operations
+/// are synchronous. This design allows:
+///
+/// 1. **Non-blocking execution**: TPM operations can run on blocking thread pools
+///    via `tokio::task::spawn_blocking` without blocking the async runtime
+/// 2. **Consistent API**: All authentication operations use async/await patterns
+/// 3. **Future extensibility**: Support for truly async TPM drivers if available
+///
+/// ## Runtime Requirements
+///
+/// Implementations that use real TPM hardware (like `RealTpmOperations`) require:
+/// - An active tokio runtime (checked via `tokio::runtime::Handle::try_current()`)
+/// - Available threads in the runtime's blocking thread pool
+///
+/// Mock implementations (like `MockTpmOperations`) don't have these requirements
+/// since they don't perform actual TPM operations.
+///
+/// ## Thread Safety
+///
+/// The `Send + Sync` bounds ensure implementations can be safely shared across
+/// threads, which is necessary for use in the async `AuthenticationClient`.
 #[async_trait::async_trait]
 pub trait TpmOperations: Send + Sync {
+    /// Generate a cryptographic proof of possession for the given challenge
+    ///
+    /// This method uses TPM2_Certify to prove possession of the Attestation Key (AK)
+    /// by certifying it with itself and including the challenge as qualifying data.
+    ///
+    /// # Arguments
+    ///
+    /// * `challenge` - Challenge string from the verifier (typically base64-encoded)
+    ///
+    /// # Returns
+    ///
+    /// A `ProofOfPossession` containing the signed attestation message and signature
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - TPM operations fail (hardware/driver issues)
+    /// - Challenge encoding is invalid
+    /// - Cryptographic operations fail
+    /// - Runtime requirements are not met (for real TPM operations)
     async fn generate_proof(
         &self,
         challenge: &str,

keylime/src/context_info.rs

@@ -445,6 +445,25 @@ impl ContextInfo {
         let mut tpm_context = self.get_mutable_tpm_context().clone();
 
         // Use TPM2_Certify to certify the AK with itself
+        //
+        // ## Async Runtime Bridge
+        //
+        // TPM operations are synchronous (blocking I/O) but we're in an async context.
+        // We use `task::spawn_blocking` to run the TPM operation on a dedicated blocking
+        // thread pool, preventing it from blocking the async executor.
+        //
+        // This is necessary because:
+        // 1. TPM hardware operations involve blocking system calls
+        // 2. The tss-esapi library provides a synchronous API
+        // 3. Blocking the async runtime would prevent other tasks from making progress
+        //
+        // Requirements:
+        // - A tokio runtime must be active when this function is called
+        // - The runtime's blocking thread pool must have available threads
+        //
+        // Error handling:
+        // - First `?` handles JoinError (if the spawned task panics)
+        // - Second `?` handles TpmError from the TPM operation itself
         let (attest, signature) = task::spawn_blocking(move || {
             tpm_context.certify_credential(
                 challenge_bytes.try_into().map_err(|_| {