style: fix grammar and wording (#647)

crates/core/src/attestation.rs

@@ -167,8 +167,7 @@ impl Body {
     /// The order of fields is not stable across versions.
     pub(crate) fn hash_fields(&self, hasher: &dyn HashAlgorithm) -> Vec<(FieldId, Hash)> {
         // CRITICAL: ensure all fields are included! If a new field is added to the
-        // struct without including it here it will not be verified to be
-        // included in the attestation.
+        // struct without including it here, it will not be included in the attestation.
         let Self {
             verifying_key,
             connection_info: conn_info,
@@ -211,10 +210,12 @@ impl Body {
         &self.connection_info.data
     }
 
+    /// Returns the server's ephemeral public key.
     pub(crate) fn server_ephemeral_key(&self) -> &ServerEphemKey {
         &self.server_ephemeral_key.data
     }
 
+    /// Returns the commitment to a server certificate.
     pub(crate) fn cert_commitment(&self) -> &ServerCertCommitment {
         &self.cert_commitment.data
     }
@@ -230,7 +231,7 @@ impl Body {
     }
 }
 
-/// An attestation.
+/// An attestation document.
 ///
 /// See [module level documentation](crate::attestation) for more information.
 #[derive(Debug, Clone, Serialize, Deserialize)]

crates/core/src/attestation/proof.rs

@@ -55,7 +55,7 @@ impl AttestationProof {
             .get(&self.signature.alg)
             .map_err(|e| AttestationError::new(ErrorKind::Provider, e))?;
 
-        // Verify body corresponding to the header.
+        // Verify that the body is corresponding to the header.
         let body = self.body.verify_with_provider(provider, &self.header)?;
 
         // Verify signature of the header.
@@ -79,12 +79,15 @@ impl AttestationProof {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub(crate) struct BodyProof {
     body: Body,
+    /// A proof of inclusion of a subset of fields in the `body`.
+    // Currently, proves the inclusion of all fields.
     proof: MerkleProof,
 }
 
 impl BodyProof {
     /// Returns a new body proof.
-    // TODO: Support including a subset of fields instead of the entire body.
+    // TODO: Support creating a proof for a subset of fields instead of the entire
+    // body.
     pub(crate) fn new(
         hasher: &dyn HashAlgorithm,
         body: Body,

crates/core/src/hash.rs

@@ -306,7 +306,7 @@ macro_rules! impl_domain_separator {
             fn domain(&self) -> &[u8] {
                 use std::sync::LazyLock;
 
-                // Computes a 16 byte hash of the types name to use as a domain separator.
+                // Computes a 16 byte hash of the type's name to use as a domain separator.
                 static DOMAIN: LazyLock<[u8; 16]> = LazyLock::new(|| {
                     let domain: [u8; 32] = blake3::hash(stringify!($type).as_bytes()).into();
                     domain[..16].try_into().unwrap()

crates/core/src/index.rs

@@ -14,9 +14,9 @@ use crate::{
 #[derive(Debug, Clone)]
 pub(crate) struct Index<T> {
     items: Vec<T>,
-    // Lookup by field id
+    // Lookup by field id.
     field_ids: HashMap<FieldId, usize>,
-    // Lookup by transcript index
+    // Lookup by transcript index.
     transcript_idxs: HashMap<Idx, usize>,
 }
 

crates/core/src/merkle.rs

@@ -5,7 +5,7 @@ use utils::iter::DuplicateCheck;
 
 use crate::hash::{Hash, HashAlgId, HashAlgorithm, TypedHash};
 
-/// Errors that can occur during operations with Merkle tree and Merkle proof
+/// Errors that can occur during operations with Merkle tree and Merkle proof.
 #[derive(Debug, thiserror::Error)]
 #[error("merkle error: {0}")]
 pub(crate) struct MerkleError(String);
@@ -26,8 +26,8 @@ pub(crate) struct MerkleProof {
 opaque_debug::implement!(MerkleProof);
 
 impl MerkleProof {
-    /// Checks if indices, hashes and leaves count are valid for the provided
-    /// root
+    /// Checks if the counts of indices, hashes, and leaves are valid for the
+    /// provided root.
     ///
     /// # Panics
     ///
@@ -158,7 +158,7 @@ mod test {
         indices.into_iter().map(|i| (i, leaves[i])).collect()
     }
 
-    // Expect Merkle proof verification to succeed
+    // Expect Merkle proof verification to succeed.
     #[rstest]
     #[case::sha2(Sha256::default())]
     #[case::blake3(Blake3::default())]
@@ -194,7 +194,7 @@ mod test {
 
         choices[1].1 = leaves[0];
 
-        // fail because the leaf is wrong
+        // Fail because the leaf is wrong.
         assert!(proof.verify(&hasher, &tree.root(), choices).is_err());
     }
 
@@ -261,7 +261,7 @@ mod test {
 
         proof.tree_len += 1;
 
-        // fail because leaf count is wrong
+        // Fail because leaf count is wrong.
         assert!(proof
             .verify(&hasher, &tree.root(), choose_leaves([2, 3, 4], &leaves))
             .is_err());
@@ -283,7 +283,7 @@ mod test {
         let mut choices = choose_leaves([2, 3, 4], &leaves);
         choices[1].0 = 1;
 
-        // fail because leaf index is wrong
+        // Fail because leaf index is wrong.
         assert!(proof.verify(&hasher, &tree.root(), choices).is_err());
     }
 
@@ -300,7 +300,7 @@ mod test {
 
         let proof = tree.proof(&[2, 3, 4]);
 
-        // trying to verify less leaves than what was included in the proof
+        // Trying to verify less leaves than what was included in the proof.
         assert!(proof
             .verify(&hasher, &tree.root(), choose_leaves([2, 3], &leaves))
             .is_err());

crates/core/src/request.rs

@@ -143,7 +143,7 @@ mod test {
 
         let transcript = Transcript::new(GET_WITH_HEADER, OK_JSON);
         let (sent_len, recv_len) = transcript.len();
-        // Plaintext encodings which the Prover obtained from GC evaluation
+        // Plaintext encodings which the Prover obtained from GC evaluation.
         let encodings_provider = encoding_provider(GET_WITH_HEADER, OK_JSON);
 
         // At the end of the TLS connection the Prover holds the:

crates/core/src/signing.rs

@@ -207,7 +207,7 @@ pub struct VerifyingKey {
 
 impl_domain_separator!(VerifyingKey);
 
-/// Error occurred while verifying a signature.
+/// Error that can occur while verifying a signature.
 #[derive(Debug, thiserror::Error)]
 #[error("signature verification failed: {0}")]
 pub struct SignatureError(String);

crates/core/src/transcript/encoding.rs

@@ -17,10 +17,10 @@ use serde::{Deserialize, Serialize};
 
 use crate::hash::{impl_domain_separator, TypedHash};
 
-/// The maximum allowed total bytelength of all committed data. Used to prevent
-/// DoS during verification. (this will cause the verifier to hash up to a max
-/// of 1GB * 128 = 128GB of plaintext encodings if the commitment type is
-/// [crate::commitment::Blake3]).
+/// The maximum allowed total bytelength of committed data for a single
+/// commitment kind. Used to prevent DoS during verification. (May cause the
+/// verifier to hash up to a max of 1GB * 128 = 128GB of data for certain kinds
+/// of encoding commitments.)
 ///
 /// This value must not exceed bcs's MAX_SEQUENCE_LENGTH limit (which is (1 <<
 /// 31) - 1 by default)

crates/core/src/transcript/encoding/proof.rs

@@ -25,9 +25,11 @@ pub(super) struct Opening {
 
 opaque_debug::implement!(Opening);
 
-/// An encoding proof.
+/// An encoding commitment proof.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct EncodingProof {
+    /// The proof of inclusion of the commitment(s) in the Merkle tree of
+    /// commitments.
     pub(super) inclusion_proof: MerkleProof,
     pub(super) openings: HashMap<usize, Opening>,
 }
@@ -84,7 +86,7 @@ impl EncodingProof {
                 ))?;
             }
 
-            // Make sure the ranges are within the bounds of the transcript
+            // Make sure the ranges are within the bounds of the transcript.
             let transcript_len = match direction {
                 Direction::Sent => sent_len,
                 Direction::Received => recv_len,

crates/core/src/transcript/encoding/tree.rs

@@ -70,7 +70,7 @@ impl EncodingTree {
     ///
     /// # Arguments
     ///
-    /// * `alg` - The hash algorithm to use.
+    /// * `hasher` - The hash algorithm to use.
     /// * `idxs` - The subsequence indices to commit to.
     /// * `provider` - The encoding provider.
     /// * `transcript_length` - The length of the transcript.

crates/notary/server/src/signing.rs

@@ -17,7 +17,7 @@ impl TryFrom<PrivateKeyInfo<'_>> for AttestationKey {
         const OID_EC_PUBLIC_KEY: ObjectIdentifier =
             ObjectIdentifier::new_unwrap("1.2.840.10045.2.1");
 
-        // For now we only support elliptic curve keys
+        // For now we only support elliptic curve keys.
         if pkcs8.algorithm.oid != OID_EC_PUBLIC_KEY {
             error!("unsupported key algorithm OID: {:?}", pkcs8.algorithm.oid);
 

crates/prover/src/notarize.rs

@@ -1,6 +1,7 @@
 //! This module handles the notarization phase of the prover.
 //!
-//! The prover deals with a TLS verifier that is only a notary.
+//! The prover interacts with a TLS verifier who acts as a Notary, i.e. the
+//! verifier produces an attestation but does not verify transcript data.
 
 use super::{state::Notarize, Prover, ProverError};
 use mpz_ot::VerifiableOTReceiver;

crates/prover/src/prove.rs

@@ -1,7 +1,7 @@
 //! This module handles the proving phase of the prover.
 //!
-//! Here the prover deals with a verifier directly, so there is no notary
-//! involved. Instead the verifier directly verifies parts of the transcript.
+//! The prover interacts with a TLS verifier directly, without involving a
+//! Notary. The verifier verifies transcript data.
 
 use super::{state::Prove as ProveState, Prover, ProverError};
 use mpz_garble::{Memory, Prove};
@@ -18,7 +18,7 @@ impl Prover<ProveState> {
         &self.state.transcript
     }
 
-    /// Prove subsequences in the transcript to the verifier.
+    /// Proves subsequences in the transcript to the verifier.
     ///
     /// # Arguments
     ///
@@ -61,7 +61,7 @@ impl Prover<ProveState> {
         Ok(())
     }
 
-    /// Finalize the proving
+    /// Finalizes the proving.
     #[instrument(parent = &self.span, level = "debug", skip_all, err)]
     pub async fn finalize(self) -> Result<(), ProverError> {
         let ProveState {
@@ -81,7 +81,7 @@ impl Prover<ProveState> {
 
                 vm.finalize().await?;
 
-                // Send identity proof to the verifier
+                // Send identity proof to the verifier.
                 io.send(ServerIdentityProof {
                     name: self.config.server_name().clone(),
                     data: server_cert_data,

crates/tls/mpc/src/follower.rs

@@ -59,11 +59,11 @@ pub struct MpcTlsFollower {
 /// Data collected by the MPC-TLS follower.
 #[derive(Debug)]
 pub struct MpcTlsFollowerData {
-    /// The server's public key
+    /// The server's ephemeral public key.
     pub server_key: PublicKey,
-    /// The total number of bytes sent
+    /// The total number of bytes sent.
     pub bytes_sent: usize,
-    /// The total number of bytes received
+    /// The total number of bytes received.
     pub bytes_recv: usize,
 }
 

crates/verifier/src/lib.rs

@@ -135,7 +135,7 @@ impl Verifier<state::Initialized> {
     /// # Arguments
     ///
     /// * `socket` - The socket to the prover.
-    /// * `signer` - The signer used to sign the notarization result.
+    /// * `config` - The attestation configuration.
     #[instrument(parent = &self.span, level = "info", skip_all, err)]
     pub async fn notarize<S: AsyncWrite + AsyncRead + Send + Unpin + 'static>(
         self,
@@ -247,7 +247,7 @@ impl Verifier<state::Closed> {
     /// Starts verification of the TLS session.
     ///
     /// This function transitions the verifier into a state where it can verify
-    /// content of the transcript.
+    /// the contents of the transcript.
     pub fn start_verify(self) -> Verifier<Verify> {
         Verifier {
             config: self.config,

crates/verifier/src/notarize.rs

@@ -1,6 +1,7 @@
 //! This module handles the notarization phase of the verifier.
 //!
-//! The TLS verifier is only a notary.
+//! The TLS verifier acts as a Notary, i.e. the verifier produces an
+//! attestation but does not verify transcript data.
 
 use super::{state::Notarize, Verifier, VerifierError};
 use mpz_ot::CommittedOTSender;
@@ -17,7 +18,7 @@ impl Verifier<Notarize> {
     ///
     /// # Arguments
     ///
-    /// * `signer` - The signer used to sign the notarization result.
+    /// * `config` - The attestation configuration.
     #[instrument(parent = &self.span, level = "debug", skip_all, err)]
     pub async fn finalize(self, config: &AttestationConfig) -> Result<Attestation, VerifierError> {
         let Notarize {
@@ -62,7 +63,7 @@ impl Verifier<Notarize> {
 
                 io.send(attestation.clone()).await?;
 
-                info!("Sent session header");
+                info!("Sent attestation");
 
                 Ok::<_, VerifierError>(attestation)
             })

crates/verifier/src/verify.rs

@@ -19,19 +19,19 @@ impl Verifier<VerifyState> {
     ///
     /// # Warning
     ///
-    /// The content of the received transcripts can not be considered authentic
+    /// The content of the received transcript can not be considered authentic
     /// until after finalization.
     #[instrument(parent = &self.span, level = "info", skip_all, err)]
     pub async fn receive(&mut self) -> Result<PartialTranscript, VerifierError> {
         self.state
             .mux_fut
             .poll_with(async {
-                // Receive partial transcript from the prover
+                // Receive partial transcript from the prover.
                 let partial_transcript: PartialTranscript = self.state.io.expect_next().await?;
 
                 info!("Received partial transcript from prover");
 
-                // Check ranges
+                // Check ranges.
                 if partial_transcript.len_sent()
                     != self.state.connection_info.transcript_length.sent as usize
                     || partial_transcript.len_received()
@@ -42,7 +42,7 @@ impl Verifier<VerifyState> {
                     ));
                 }
 
-                // Now verify the transcript parts which the prover wants to reveal
+                // Now verify the transcript parts which the prover wants to reveal.
                 let sent_value_ids =
                     get_value_ids(Direction::Sent, partial_transcript.sent_authed());
                 let recv_value_ids =
@@ -64,10 +64,10 @@ impl Verifier<VerifyState> {
                     .map(Value::U8)
                     .collect::<Vec<_>>();
 
-                // Check that purported values are correct
+                // Check that purported values are correct.
                 self.state.vm.verify(&value_refs, &values).await?;
 
-                info!("Successfully verified purported cleartext");
+                info!("Successfully verified purported transcript");
 
                 Ok::<_, VerifierError>(partial_transcript)
             })