misc: clean up comments, logs, and errors

Assorted fixes to text. No functional changes.

Signed-off-by: Tobin Feldman-Fitzthum <tobin@ibm.com>

kbs/src/error.rs

@@ -82,7 +82,7 @@ impl ResponseError for Error {
         let mut detail = String::new();
 
         // The write macro here will only raise error when OOM of the string.
-        write!(&mut detail, "{}", self).expect("written error response failed");
+        write!(&mut detail, "{}", self).expect("Failed to write error");
         let info = ErrorInformation {
             error_type: format!("{ERROR_TYPE_PREFIX}/{}", self.as_ref()),
             detail,
@@ -91,9 +91,9 @@ impl ResponseError for Error {
         // All the fields inside the ErrorInfo are printable characters, so this
         // error cannot happen.
         // A test covering all the possible error types are given to ensure this.
-        let body = serde_json::to_string(&info).expect("serialize error response failed");
+        let body = serde_json::to_string(&info).expect("Failed to serialize error");
 
-        // Due to the definition of KBS attestation protocol, we set the http code.
+        // Per the KBS protocol, errors should yield 401 or 404 reponses
         let mut res = match self {
             Error::IllegalAccessedPath { .. } | Error::PluginNotFound { .. } => {
                 HttpResponse::NotFound()

kbs/src/token/error.rs

@@ -22,7 +22,7 @@ pub enum Error {
         source: anyhow::Error,
     },
 
-    #[error("Tee public key is not found inside the claims of token")]
+    #[error("Tee public key not found in Attestation Token")]
     NoTeePubKeyClaimFound,
 
     #[error("Failed to parse Tee public key")]

kbs/src/token/mod.rs

@@ -31,22 +31,27 @@ pub struct AttestationTokenVerifierConfig {
     /// This field will default to an empty vector.
     pub extra_teekey_paths: Vec<String>,
 
-    /// Trusted Certificates file (PEM format) paths use to verify Attestation
-    /// Token Signature.
+    /// File paths of trusted certificates in PEM format used to verify
+    /// the signature of the Attestation Token.
     #[serde(default)]
     pub trusted_certs_paths: Vec<String>,
 
-    /// Urls (file:// and https:// schemes accepted) pointing to a local JWKSet file
+    /// URLs (file:// and https:// schemes accepted) pointing to a local JWKSet file
     /// or to an OpenID configuration url giving a pointer to JWKSet certificates
     /// (for "Jwk") to verify Attestation Token Signature.
     #[serde(default)]
     pub trusted_jwk_sets: Vec<String>,
 
-    /// Whether a JWK that directly comes from the JWT token is allowed to verify
-    /// the signature. This is insecure as it will not check the endorsement of
-    /// the JWK. If this option is set to false, the JWK will be looked up from
-    /// the key store configured during launching the KBS with kid field in the JWT,
-    /// or be checked against the configured trusted CA certs.
+    /// Whether the token signing key is (not) validated.
+    /// If true, the attestation token can be modified in flight.
+    /// This should only be set to true for testing.
+    /// While the token signature is still validated, the provenance of the
+    /// signing key is not checked and the key could be replaced.
+    ///
+    /// When false, the key must be endorsed by the certificates or JWK sets
+    /// specified above.
+    ///
+    /// Default: false
     #[serde(default = "bool::default")]
     pub insecure_key: bool,
 }
@@ -81,8 +86,10 @@ impl TokenVerifier {
         })
     }
 
-    /// Different attestation service would embed tee public key
-    /// in different parts of the claims.
+    /// Different types of attestation tokens store the tee public key in
+    /// different places.
+    /// Try extracting the key from multiple built-in paths as well as any extras
+    /// specified in the config file.
     pub fn extract_tee_public_key(&self, claim: Value) -> Result<TeePubKey> {
         for path in &self.extra_teekey_paths {
             if let Some(pkey_value) = claim.pointer(path) {