From 38104bca1a12d7dc49b2fc62b74b0e29b4bb2572 Mon Sep 17 00:00:00 2001 From: dan Date: Tue, 22 Oct 2024 08:31:13 +0200 Subject: [PATCH] style: fix grammar and wording (#647) --- crates/core/src/attestation.rs | 7 ++++--- crates/core/src/attestation/proof.rs | 7 +++++-- crates/core/src/hash.rs | 2 +- crates/core/src/index.rs | 4 ++-- crates/core/src/merkle.rs | 16 ++++++++-------- crates/core/src/request.rs | 2 +- crates/core/src/signing.rs | 2 +- crates/core/src/transcript/encoding.rs | 8 ++++---- crates/core/src/transcript/encoding/proof.rs | 6 ++++-- crates/core/src/transcript/encoding/tree.rs | 2 +- crates/notary/server/src/signing.rs | 2 +- crates/prover/src/notarize.rs | 3 ++- crates/prover/src/prove.rs | 10 +++++----- crates/tls/mpc/src/follower.rs | 6 +++--- crates/verifier/src/lib.rs | 4 ++-- crates/verifier/src/notarize.rs | 7 ++++--- crates/verifier/src/verify.rs | 12 ++++++------ 17 files changed, 54 insertions(+), 46 deletions(-) diff --git a/crates/core/src/attestation.rs b/crates/core/src/attestation.rs index b9696ef2e0..4f2f8857f9 100644 --- a/crates/core/src/attestation.rs +++ b/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)] diff --git a/crates/core/src/attestation/proof.rs b/crates/core/src/attestation/proof.rs index b0be78a45a..1998e7a8f7 100644 --- a/crates/core/src/attestation/proof.rs +++ b/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, diff --git a/crates/core/src/hash.rs b/crates/core/src/hash.rs index 94c21e44c9..9881711683 100644 --- a/crates/core/src/hash.rs +++ b/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() diff --git a/crates/core/src/index.rs b/crates/core/src/index.rs index 6e974f5ef0..6d9daa7a20 100644 --- a/crates/core/src/index.rs +++ b/crates/core/src/index.rs @@ -14,9 +14,9 @@ use crate::{ #[derive(Debug, Clone)] pub(crate) struct Index { items: Vec, - // Lookup by field id + // Lookup by field id. field_ids: HashMap, - // Lookup by transcript index + // Lookup by transcript index. transcript_idxs: HashMap, } diff --git a/crates/core/src/merkle.rs b/crates/core/src/merkle.rs index ebb200c170..ba48fd0d02 100644 --- a/crates/core/src/merkle.rs +++ b/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()); diff --git a/crates/core/src/request.rs b/crates/core/src/request.rs index 32818ac6d7..ae1bc4ebf7 100644 --- a/crates/core/src/request.rs +++ b/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: diff --git a/crates/core/src/signing.rs b/crates/core/src/signing.rs index eb2c902231..a26b616702 100644 --- a/crates/core/src/signing.rs +++ b/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); diff --git a/crates/core/src/transcript/encoding.rs b/crates/core/src/transcript/encoding.rs index 940c821d63..9041eba75c 100644 --- a/crates/core/src/transcript/encoding.rs +++ b/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) diff --git a/crates/core/src/transcript/encoding/proof.rs b/crates/core/src/transcript/encoding/proof.rs index ead2a25b5b..231340c4b2 100644 --- a/crates/core/src/transcript/encoding/proof.rs +++ b/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, } @@ -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, diff --git a/crates/core/src/transcript/encoding/tree.rs b/crates/core/src/transcript/encoding/tree.rs index 22df01e58a..35ecbf2c4e 100644 --- a/crates/core/src/transcript/encoding/tree.rs +++ b/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. diff --git a/crates/notary/server/src/signing.rs b/crates/notary/server/src/signing.rs index 6d990485a2..33ff65fa8a 100644 --- a/crates/notary/server/src/signing.rs +++ b/crates/notary/server/src/signing.rs @@ -17,7 +17,7 @@ impl TryFrom> 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); diff --git a/crates/prover/src/notarize.rs b/crates/prover/src/notarize.rs index 206322377c..3e01d8a647 100644 --- a/crates/prover/src/notarize.rs +++ b/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; diff --git a/crates/prover/src/prove.rs b/crates/prover/src/prove.rs index 8163b18d8b..947900f434 100644 --- a/crates/prover/src/prove.rs +++ b/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 { &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 { 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 { 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, diff --git a/crates/tls/mpc/src/follower.rs b/crates/tls/mpc/src/follower.rs index 2945b38c67..417cab3162 100644 --- a/crates/tls/mpc/src/follower.rs +++ b/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, } diff --git a/crates/verifier/src/lib.rs b/crates/verifier/src/lib.rs index 0ef5e457cd..1d746545b6 100644 --- a/crates/verifier/src/lib.rs +++ b/crates/verifier/src/lib.rs @@ -135,7 +135,7 @@ impl Verifier { /// # 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( self, @@ -247,7 +247,7 @@ impl Verifier { /// 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 { Verifier { config: self.config, diff --git a/crates/verifier/src/notarize.rs b/crates/verifier/src/notarize.rs index 5b0d78026a..939d91bf2a 100644 --- a/crates/verifier/src/notarize.rs +++ b/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 { /// /// # 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 { let Notarize { @@ -62,7 +63,7 @@ impl Verifier { io.send(attestation.clone()).await?; - info!("Sent session header"); + info!("Sent attestation"); Ok::<_, VerifierError>(attestation) }) diff --git a/crates/verifier/src/verify.rs b/crates/verifier/src/verify.rs index 83141d4b50..e3ebf893c3 100644 --- a/crates/verifier/src/verify.rs +++ b/crates/verifier/src/verify.rs @@ -19,19 +19,19 @@ impl Verifier { /// /// # 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 { 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 { )); } - // 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 { .map(Value::U8) .collect::>(); - // 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) })