From 865127129a1e913866390ac8193ec89acec3756a Mon Sep 17 00:00:00 2001 From: Daniel Schadt Date: Sun, 26 Nov 2023 23:21:51 +0100 Subject: basic README and copyright texts --- src/lib.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) (limited to 'src') diff --git a/src/lib.rs b/src/lib.rs index ce38f07..6b17499 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,57 @@ +//! Implementation of Hierarchical Identity Based Encryption ([HIBE]), an extension of Identity +//! Based Encryption ([IBE]). +//! +//! # ⚠️ Warning: Cryptographic Hazmat ☣️ +//! +//! This crate is made for playing around with HIBE and for prototyping of applications and +//! protocols using HIBE. It has *not* been audited, it is *not* battle tested, and *nobody* claims +//! it to be secure. +//! +//! Use it at **your own risk** and if you know what you are doing! +//! +//! # Introduction +//! +//! HIBEs are encryption schemes in which a party can encrypt data for a given recipient by using +//! the recipient's identity in the encryption process, instead of requiring an explicitely shared +//! public key. In addition, the hierarchical property allows holders of a secret key for an +//! identity to also generate the keys of subordinate identities. +//! +//! This library is intended to provide an easy-to-use implementation of HIBE for prototyping and +//! playing around. The library is not optimized for speed, but rather for usability (for example, +//! it requires the standard library and allocations, and it unconditionally requires `serde` for +//! serialization). +//! +//! # Crate Structure +//! +//! The [`hibe`] submodule contains the basic definitions of HIBE functionality, as [`hibe::Hibe`] +//! (basic parameter and key generation), [`hibe::HibeKem`] (HIBE key encapsulation) and +//! [`hibe::HibeCrypt`] (HIBE encryption). Those methods work directly on the group elements, as +//! they are defined in their respective papers. +//! +//! To aid in using those algorithms, a higher-level wrapper is provided in the [`kem`] submodule, +//! mainly in the [`kem::HybridKem`] struct. This allows you to deal with bytes instead of group +//! elements. +//! +//! The bridge between [`hibe`] and [`kem`] is provided by [`Mapper`], which translates from +//! arbitrary identities from the application domain to the low-level, mathematical representation +//! of identities in the context of HIBEs. +//! +//! Currently, [`kem::HybridKem`] is hardwired to [`hibe::BonehBoyenGoh`] to keep the amount of +//! generics and generic bounds low. This might change in the future, when more HIBEs might be +//! implemented. +//! +//! # Implemented Algorithms +//! +//! Currenly, this crate implements the HIBE of Boneh, Boyen and Goh, "Hierarchical Identity Based +//! Encryption with Constant Size Ciphertext" ([eprint](https://eprint.iacr.org/2005/015.pdf)). +//! This algorithm lives as [`hibe::BonehBoyenGoh`]. +//! +//! The algorithms in this crate are implemented on top of +//! [`bls_12_381_plus`](https://crates.io/crates/bls12_381_plus), as it provides better `serde` +//! support and access to the internals of the group elements. +//! +//! [HIBE]: https://cryptowiki.tm.kit.edu/index.php/Hierarchical_Identity-Based_Encryption +//! [IBE]: https://en.wikipedia.org/wiki/Identity-based_encryption pub mod error; pub mod hibe; pub mod kem; -- cgit v1.2.3