From cb37e1663b999478e4f3690a3ce82b3388807d55 Mon Sep 17 00:00:00 2001 From: dan Date: Fri, 10 May 2024 15:34:30 +0300 Subject: [PATCH] docs: misc comments for MPCOT and Ferret-core --- mpz-core/src/lpn.rs | 12 ++++-------- ot/mpz-ot-core/src/ferret/cuckoo.rs | 2 +- ot/mpz-ot-core/src/ferret/mod.rs | 2 +- ot/mpz-ot-core/src/ferret/mpcot/receiver.rs | 11 +++++++---- .../src/ferret/mpcot/receiver_regular.rs | 14 +++++++++----- ot/mpz-ot-core/src/ferret/mpcot/sender.rs | 10 +++++----- ot/mpz-ot-core/src/ferret/mpcot/sender_regular.rs | 11 ++++++----- ot/mpz-ot-core/src/ferret/receiver.rs | 12 ++++-------- ot/mpz-ot-core/src/ferret/sender.rs | 4 ++-- ot/mpz-ot-core/src/ideal/ideal_spcot.rs | 6 ++++-- 10 files changed, 43 insertions(+), 41 deletions(-) diff --git a/mpz-core/src/lpn.rs b/mpz-core/src/lpn.rs index cd99ca3d..3350e028 100644 --- a/mpz-core/src/lpn.rs +++ b/mpz-core/src/lpn.rs @@ -112,10 +112,10 @@ impl LpnEncoder { } } -/// Lpn paramters +/// LPN parameters. #[derive(Copy, Clone, Debug)] pub struct LpnParameters { - /// The length of output vecotrs. + /// The length of output vectors. pub n: usize, /// The length of the secret vector pub k: usize, @@ -156,9 +156,7 @@ impl LpnParameters { #[cfg(test)] mod tests { - use crate::lpn::LpnEncoder; - use crate::prp::Prp; - use crate::Block; + use crate::{lpn::LpnEncoder, prp::Prp, Block}; impl LpnEncoder { #[allow(dead_code)] @@ -202,9 +200,7 @@ mod tests { #[test] fn lpn_test() { - use crate::lpn::LpnEncoder; - use crate::prg::Prg; - use crate::Block; + use crate::{lpn::LpnEncoder, prg::Prg, Block}; let k = 20; let n = 200; diff --git a/ot/mpz-ot-core/src/ferret/cuckoo.rs b/ot/mpz-ot-core/src/ferret/cuckoo.rs index 938e2f03..7944c85b 100644 --- a/ot/mpz-ot-core/src/ferret/cuckoo.rs +++ b/ot/mpz-ot-core/src/ferret/cuckoo.rs @@ -142,7 +142,7 @@ pub(crate) fn hash_to_index(hash: &AesEncryptor, range: usize, value: u32) -> us (res as usize) % range } -// Finds the position of the item in each Bucket. +// Finds the position of the `item` in the given `bucket`. #[inline(always)] pub(crate) fn find_pos(bucket: &[Item], item: &Item) -> Result { let pos = bucket.iter().position(|&x| *item == x); diff --git a/ot/mpz-ot-core/src/ferret/mod.rs b/ot/mpz-ot-core/src/ferret/mod.rs index 9b52fded..6a5f7672 100644 --- a/ot/mpz-ot-core/src/ferret/mod.rs +++ b/ot/mpz-ot-core/src/ferret/mod.rs @@ -13,7 +13,7 @@ pub mod spcot; /// Computational security parameter pub const CSP: usize = 128; -/// Number of hashes in Cuckoo hash. +/// Number of hash functions in Cuckoo hash. pub const CUCKOO_HASH_NUM: usize = 3; /// Trial numbers in Cuckoo hash insertion. diff --git a/ot/mpz-ot-core/src/ferret/mpcot/receiver.rs b/ot/mpz-ot-core/src/ferret/mpcot/receiver.rs index 0f8613af..b4cbee59 100644 --- a/ot/mpz-ot-core/src/ferret/mpcot/receiver.rs +++ b/ot/mpz-ot-core/src/ferret/mpcot/receiver.rs @@ -50,7 +50,10 @@ impl Receiver { impl Receiver { /// Performs the hash procedure in MPCOT extension. - /// Outputs the length of each bucket plus 1. + /// + /// For each bucket outputs a tuple: + /// - the base 2 logarithm (rounded up) of the length of the bucket + /// - the position of an index in the bucket /// /// See Step 1 to Step 4 in Figure 7. /// @@ -71,7 +74,7 @@ impl Receiver { } let cuckoo = CuckooHash::new(self.state.hashes.clone()); - // Inserts all the alpha's. + // Inserts all the alphas. let table = cuckoo.insert(alphas)?; let m = table.len(); @@ -201,7 +204,7 @@ pub mod state { /// /// In this state the receiver performs pre extension in MPCOT (potentially multiple times). pub struct PreExtension { - /// Current MPCOT counter + /// Current MPCOT extension counter. pub(super) counter: usize, /// The hashes to generate Cuckoo hash table. pub(super) hashes: Arc<[AesEncryptor; CUCKOO_HASH_NUM]>, @@ -214,7 +217,7 @@ pub mod state { /// /// In this state the receiver performs MPCOT extension (potentially multiple times). pub struct Extension { - /// Current MPCOT counter + /// Current MPCOT extension counter. pub(super) counter: usize, /// Current length of Cuckoo hash table, will possibly be changed in each extension. pub(super) m: usize, diff --git a/ot/mpz-ot-core/src/ferret/mpcot/receiver_regular.rs b/ot/mpz-ot-core/src/ferret/mpcot/receiver_regular.rs index 2b226108..9c4089ed 100644 --- a/ot/mpz-ot-core/src/ferret/mpcot/receiver_regular.rs +++ b/ot/mpz-ot-core/src/ferret/mpcot/receiver_regular.rs @@ -1,4 +1,5 @@ //! MPCOT receiver for regular indices. Regular indices means the indices are evenly distributed. +//! See "Optimization for regular indices" in §5. use mpz_core::Block; @@ -26,8 +27,11 @@ impl Receiver { } } impl Receiver { - /// Performs the prepare procedure in MPCOT extension. - /// Outputs the indices for SPCOT. + /// Performs the preparation procedure in MPCOT extension. + /// + /// For each call to be made to SPCOT outputs a tuple: + /// - the base 2 logarithm (rounded up) of the length of the choice-bit vector + /// - the index of the point in the vector /// /// # Arguments. /// @@ -46,7 +50,7 @@ impl Receiver { )); } - // The range of each interval. + // The size of each interval. let k = (n + t - 1) / t; let queries_length = if n % t == 0 { @@ -163,7 +167,7 @@ pub mod state { /// /// In this state the receiver performs pre extension in MPCOT (potentially multiple times). pub struct PreExtension { - /// Current MPCOT counter + /// Current MPCOT extension counter. pub(super) counter: usize, } @@ -175,7 +179,7 @@ pub mod state { /// /// In this state the receiver performs MPCOT extension (potentially multiple times). pub struct Extension { - /// Current MPCOT counter + /// Current MPCOT extension counter. #[allow(dead_code)] pub(super) counter: usize, /// The total number of indices in the current extension. diff --git a/ot/mpz-ot-core/src/ferret/mpcot/sender.rs b/ot/mpz-ot-core/src/ferret/mpcot/sender.rs index f1e49105..738f67c7 100644 --- a/ot/mpz-ot-core/src/ferret/mpcot/sender.rs +++ b/ot/mpz-ot-core/src/ferret/mpcot/sender.rs @@ -187,7 +187,7 @@ pub mod state { pub struct PreExtension { /// Sender's global secret. pub(super) delta: Block, - /// Current MPCOT counter + /// Current MPCOT extension counter. pub(super) counter: usize, /// The hashes to generate Cuckoo hash table. pub(super) hashes: Arc<[AesEncryptor; CUCKOO_HASH_NUM]>, @@ -202,18 +202,18 @@ pub mod state { pub struct Extension { /// Sender's global secret. pub(super) delta: Block, - /// Current MPCOT counter + /// Current MPCOT extension counter. pub(super) counter: usize, /// Current length of Cuckoo hash table, will possibly be changed in each extension. pub(super) m: usize, /// The total number of indices in the current extension. pub(super) n: u32, - /// The hashes to generate Cuckoo hash table. + /// The hash functions to generate Cuckoo hash table. pub(super) hashes: Arc<[AesEncryptor; CUCKOO_HASH_NUM]>, - /// The buckets contains all the hash values. + /// The buckets containing all the hash values. pub(super) buckets: Vec>, - /// The padded buckets length (power of 2). + /// The padded length of each bucket (power of 2). pub(super) buckets_length: Vec, } diff --git a/ot/mpz-ot-core/src/ferret/mpcot/sender_regular.rs b/ot/mpz-ot-core/src/ferret/mpcot/sender_regular.rs index db0646b6..43499469 100644 --- a/ot/mpz-ot-core/src/ferret/mpcot/sender_regular.rs +++ b/ot/mpz-ot-core/src/ferret/mpcot/sender_regular.rs @@ -1,4 +1,5 @@ //! MPCOT sender for regular indices. Regular indices means the indices are evenly distributed. +//! See "Optimization for regular indices" in §5. use mpz_core::Block; @@ -31,7 +32,7 @@ impl Sender { } impl Sender { - /// Performs the prepare procedure in MPCOT extension. + /// Performs the preparation procedure in MPCOT extension. /// Outputs the information for SPCOT. /// /// # Arguments. @@ -49,7 +50,7 @@ impl Sender { )); } - // The range of each interval. + // The size of each interval. let k = (n + t - 1) / t; let queries_length = if n % t == 0 { @@ -69,7 +70,7 @@ impl Sender { let mut queries_depth = Vec::with_capacity(queries_length.len()); for len in queries_length.iter() { - // pad `len`` to power of 2. + // pad `len` to power of 2. let power = len .checked_next_power_of_two() .expect("len should be less than usize::MAX / 2 - 1") @@ -156,7 +157,7 @@ pub mod state { pub struct PreExtension { /// Sender's global secret. pub(super) delta: Block, - /// Current MPCOT counter + /// Current MPCOT extension counter. pub(super) counter: usize, } @@ -169,7 +170,7 @@ pub mod state { pub struct Extension { /// Sender's global secret. pub(super) delta: Block, - /// Current MPCOT counter + /// Current MPCOT extension counter. pub(super) counter: usize, /// The total number of indices in the current extension. pub(super) n: u32, diff --git a/ot/mpz-ot-core/src/ferret/receiver.rs b/ot/mpz-ot-core/src/ferret/receiver.rs index 4f94e6e6..d2db614b 100644 --- a/ot/mpz-ot-core/src/ferret/receiver.rs +++ b/ot/mpz-ot-core/src/ferret/receiver.rs @@ -67,12 +67,8 @@ impl Receiver { } impl Receiver { - /// The prepare precedure of extension, sample error vectors and outputs information for MPCOT. + /// The preparation procedure of extension. Samples error vectors and outputs information for MPCOT. /// See step 3 and 4. - /// - /// # Arguments. - /// - /// * `lpn_type` - The type of LPN parameters. pub fn get_mpcot_query(&mut self) -> (Vec, usize, usize) { match self.state.lpn_type { LpnType::Uniform => { @@ -97,7 +93,7 @@ impl Receiver { } /// Performs the Ferret extension. - /// Outputs exactly l = n - t COTs. + /// Outputs exactly l = n - k COTs. /// /// See step 5 and 6. /// @@ -162,9 +158,9 @@ pub mod state { /// The receiver's state after the setup phase. /// - /// In this state the sender performs Ferret extension (potentially multiple times). + /// In this state the receiver performs Ferret extension (potentially multiple times). pub struct Extension { - /// Current Ferret counter. + /// Current Ferret extension counter. pub(super) counter: usize, /// Lpn parameters. diff --git a/ot/mpz-ot-core/src/ferret/sender.rs b/ot/mpz-ot-core/src/ferret/sender.rs index 9e8db180..e8cb64d8 100644 --- a/ot/mpz-ot-core/src/ferret/sender.rs +++ b/ot/mpz-ot-core/src/ferret/sender.rs @@ -71,7 +71,7 @@ impl Sender { } /// Performs the Ferret extension. - /// Outputs exactly l = n-t COTs. + /// Outputs exactly l = n-k COTs. /// /// See step 5 and 6. /// @@ -128,7 +128,7 @@ pub mod state { /// Sender's global secret. #[allow(dead_code)] pub(super) delta: Block, - /// Current Ferret counter. + /// Current Ferret extension counter. pub(super) counter: usize, /// Lpn type. diff --git a/ot/mpz-ot-core/src/ideal/ideal_spcot.rs b/ot/mpz-ot-core/src/ideal/ideal_spcot.rs index c30a5fb9..e298b991 100644 --- a/ot/mpz-ot-core/src/ideal/ideal_spcot.rs +++ b/ot/mpz-ot-core/src/ideal/ideal_spcot.rs @@ -48,9 +48,11 @@ impl IdealSpcot { /// Performs the batch extension of SPCOT. /// - /// # Argument + /// # Arguments /// - /// * `pos` - The positions in each extension. + /// * `pos` - For each extension contains a tuple: + /// - the length of the choice-bit vector + /// - the index of the point in the vector pub fn extend(&mut self, pos: &[(usize, u32)]) -> (SpcotMsgForSender, SpcotMsgForReceiver) { let mut v = vec![]; let mut w = vec![];