diff options
| -rw-r--r-- | src/hibe/mod.rs | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/src/hibe/mod.rs b/src/hibe/mod.rs index 20d83a6..b213d9e 100644 --- a/src/hibe/mod.rs +++ b/src/hibe/mod.rs @@ -1,3 +1,26 @@ +//! Low-level implementation of HIBE primitives. +//! +//! The structs and traits in this module implement HIBEs in the way that they are defined in their +//! respective papers. For a higher-level interface, refer to the [`kem`][super::kem] module. +//! +//! To make this module more flexible, all methods that use randomness only use the [`Rng`] bound, +//! not [`CryptoRng`][rand::CryptoRng]. This does not mean that you should use them with insecure +//! randomness, but rather that you need to take care when using these low-level primitives! +//! +//! # Identity Handling +//! +//! This module assumes that identity hierarchies are represented by sequences of "identity +//! elements". The type of the identity elements is defined by the actual HIBE algorithm, but +//! usually ends up being a [`Scalar`][bls12_381_plus::Scalar]. The assumption is that the more +//! elements are provided, the deeper down the hierarchy goes. For example: +//! +//! ```ignore +//! let root = &[]; // Represents the root identity +//! let a = &[1]; +//! let b = &[1, 1]; // ... is a descendent of a +//! let c = &[1, 2]; // ... is also a descendent of a and a sibling of b +//! let d = &[2]; // ... is a sibling of a +//! ``` use super::error::Result; use rand::Rng; @@ -5,14 +28,50 @@ use rand::Rng; mod bbg; pub use self::bbg::BonehBoyenGoh; +/// Main trait for HIBE schemes. +/// +/// This trait defines the basic functionality of HIBEs, namely the generation and derivation of +/// secret keys for identities. +/// +/// For encryption functionality, the extension [`HibeCrypt`] needs to be used, and for key +/// encapsulation, [`HibeKem`]. +/// +/// Note that this trait represents a HIBE *algorithm* not a HIBE *instantiation*. pub trait Hibe { + /// Type of the private key. + /// + /// This refers to a single identity's private key. type PrivateKey; + /// Type of the master key. + /// + /// This is the secret key that can be used to generate the secret key of any identity. type MasterKey; + /// Type of the public key. + /// + /// As HIBEs use identities to derive public keys, this is the public key "of the whole + /// system", sometimes also called *master public key* or *system parameters*. There is no + /// distinct type to represent the public key of a single identity, as many schemes compute + /// that implicitely in the encryption functionality. type PublicKey; + /// Type of an identity element. + /// + /// The whole identity is represented by multiple [`Identity`][Self::Identity] elements, for + /// example in a `&[Identity]` slice. type Identity; + /// Set the system up. + /// + /// This method outputs the master public key and the master secret key. fn setup<R: Rng>(&self, rng: R) -> Result<(Self::PublicKey, Self::MasterKey)>; + /// Generate the key for the given identity. + /// + /// Parameters: + /// + /// * `rng` - The randomness to use. + /// * `public_key` - The master public key. + /// * `master_key` - The master secret key. + /// * `identity` - The identity elements. fn generate_key<R: Rng>( &self, rng: R, @@ -21,6 +80,15 @@ pub trait Hibe { identity: &[Self::Identity], ) -> Result<Self::PrivateKey>; + /// Derives a key from the given parent identity. + /// + /// Parameters: + /// + /// * `rng` - The randomness to use. + /// * `public_key` - The master public key. + /// * `parent_key` - The parent's secret key. + /// * `parent_name` - The identity of the parent. + /// * `child` - Which child element to generate the key for. fn derive_key<R: Rng>( &self, rng: R, @@ -31,10 +99,21 @@ pub trait Hibe { ) -> Result<Self::PrivateKey>; } +/// HIBE methods to do encryption. pub trait HibeCrypt: Hibe { + /// Type of the messages that this HIBE can encrypt. type Message; + /// Type of the resulting ciphertext. type Ciphertext; + /// Encrypt a message for the given identity. + /// + /// Parameters: + /// + /// * `rng` - The randomness to use. + /// * `public_key` - The master public key. + /// * `identity` - The identity for which to encrypt the message. + /// * `message` - The actual message. fn encrypt<R: Rng>( &self, rng: R, @@ -43,6 +122,7 @@ pub trait HibeCrypt: Hibe { message: &Self::Message, ) -> Result<Self::Ciphertext>; + /// Decrypt a message given the secret key. fn decrypt( &self, public_key: &Self::PublicKey, @@ -51,10 +131,22 @@ pub trait HibeCrypt: Hibe { ) -> Result<Self::Message>; } +/// HIBE methods to do key encapsulation. pub trait HibeKem: Hibe { + /// Type of the resulting key. type Key; + /// Type of the encapsulation of the key. type EncapsulatedKey; + /// Computes a key encapsulation. + /// + /// Returns the generated key and its encapsulation. + /// + /// Parameters: + /// + /// * `rng` - The randomness to use. + /// * `public_key` - The master public key. + /// * `identity` - The identity for which to encapsulate the key. fn encapsulate<R: Rng>( &self, rng: R, @@ -62,6 +154,7 @@ pub trait HibeKem: Hibe { identity: &[Self::Identity], ) -> Result<(Self::Key, Self::EncapsulatedKey)>; + /// Decapsulate a previously encapsulated key. fn decapsulate( &self, public_key: &Self::PublicKey, |