From 5dfb7d4461154d50fb5d88f6c9d0c13d3f767f6d Mon Sep 17 00:00:00 2001
From: Daniel Schadt <kingdread@gmx.de>
Date: Mon, 27 Nov 2023 17:18:27 +0100
Subject: more documentation
---
src/hibe/mod.rs | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 93 insertions(+)
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,
--
cgit v1.2.3