diff --git a/tfhe/src/core_crypto/entities/lwe_public_key.rs b/tfhe/src/core_crypto/entities/lwe_public_key.rs index e57a0d2d9..58737e610 100644 --- a/tfhe/src/core_crypto/entities/lwe_public_key.rs +++ b/tfhe/src/core_crypto/entities/lwe_public_key.rs @@ -4,6 +4,20 @@ use crate::core_crypto::entities::*; // An LwePublicKey is literally an LweCiphertextList, so we wrap an LweCiphertextList and use // Deref to have access to all the primitives of the LweCiphertextList easily + +/// A [`public LWE bootstrap key`](`LwePublicKey`). +/// +/// This is a wrapper type of [`LweCiphertextList`], [`std::ops::Deref`] and [`std::ops::DerefMut`] +/// are implemented to dereference to the underlying [`LweCiphertextList`] for ease of use. See +/// [`LweCiphertextList`] for additional methods. +/// +/// # Formal Definition +/// +/// ## LWE Public Key +/// +/// An LWE public key contains $m$ LWE encryptions of 0 under a secret key +/// $\vec{s}\in\mathbb{Z}\_q^n$ where $n$ is the LWE dimension of the ciphertexts contained in the +/// public key. #[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)] pub struct LwePublicKey { lwe_list: LweCiphertextList, @@ -24,6 +38,46 @@ impl std::ops::DerefMut for LwePublicKey { } impl> LwePublicKey { + /// Create an [`LwePublicKey`] from an existing container. + /// + /// # Note + /// + /// This function only wraps a container in the appropriate type. If you want to generate an + /// [`LwePublicKey`] you need to call + /// [`crate::core_crypto::algorithms::generate_lwe_public_key`] using this key as output. + /// + /// This docstring exhibits [`LwePublicKey`] primitives usage. + /// + /// ``` + /// use tfhe::core_crypto::prelude::*; + /// + /// // Define parameters for LwePublicKey creation + /// let lwe_size = LweSize(600); + /// let zero_encryption_count = LwePublicKeyZeroEncryptionCount(3); + /// + /// // Create a new LwePublicKey + /// let lwe_public_key = LwePublicKey::new(0u64, lwe_size, zero_encryption_count); + /// + /// // This is a method from LweCiphertextList + /// assert_eq!(lwe_public_key.lwe_size(), lwe_size); + /// // This is a method from LwePublicKey + /// assert_eq!( + /// lwe_public_key.zero_encryption_count(), + /// zero_encryption_count + /// ); + /// + /// // Demonstrate how to recover the allocated container + /// let underlying_container: Vec = lwe_public_key.into_container(); + /// + /// // Recreate a list using from_container + /// let lwe_public_key = LwePublicKey::from_container(underlying_container, lwe_size); + /// + /// assert_eq!(lwe_public_key.lwe_size(), lwe_size); + /// assert_eq!( + /// lwe_public_key.zero_encryption_count(), + /// zero_encryption_count + /// ); + /// ``` pub fn from_container(container: C, lwe_size: LweSize) -> LwePublicKey { assert!( container.container_len() > 0, @@ -34,30 +88,48 @@ impl> LwePublicKey { } } + /// Return the [`LwePublicKeyZeroEncryptionCount`] of the [`LwePublicKey`]. + /// + /// See [`LwePublicKey::from_container`] for usage. pub fn zero_encryption_count(&self) -> LwePublicKeyZeroEncryptionCount { LwePublicKeyZeroEncryptionCount(self.lwe_ciphertext_count().0) } /// Consume the entity and return its underlying container. + /// + /// See [`LwePublicKey::from_container`] for usage. pub fn into_container(self) -> C { self.lwe_list.into_container() } + /// Return a view of the [`LwePublicKey`]. This is useful if an algorithm takes a view by + /// value. pub fn as_view(&self) -> LwePublicKey<&'_ [Scalar]> { LwePublicKey::from_container(self.as_ref(), self.lwe_size()) } } impl> LwePublicKey { + /// Mutable variant of [`LwePublicKey::as_view`]. pub fn as_mut_view(&mut self) -> LwePublicKey<&'_ mut [Scalar]> { let lwe_size = self.lwe_size(); LwePublicKey::from_container(self.as_mut(), lwe_size) } } +/// A [`LwePublicKey`] owning the memory for its own storage. pub type LwePublicKeyOwned = LwePublicKey>; impl LwePublicKeyOwned { + /// Allocate memory and create a new owned [`LwePublicKey`]. + /// + /// # Note + /// + /// This function allocates a vector of the appropriate size and wraps it in the appropriate + /// type. If you want to generate an [`LwePublicKey`] you need to call + /// [`crate::core_crypto::algorithms::generate_lwe_public_key`] using this key as output. + /// + /// See [`LwePublicKey::from_container`] for usage. pub fn new( fill_with: Scalar, lwe_size: LweSize,