human_key 0.1.0-alpha.1

Pure Rust implementation of human-derived attribute fingerprinting for cryptographic key derivation.
Documentation
//! A pure Rust implementation of Human Keys, providing a method of
//! human-derived attribute fingerprinting for cryptographic key derivation.
//!
//! Browser and device fingerprinting derives a stable, unique identifier from
//! a collection of otherwise unremarkable signals: screen size, installed
//! fonts, timezone, operating system. None of these are secret or unique
//! alone, but their combination is. Human Keys applies the same concept to
//! human-derived attributes (name, date of birth, occupation, etc.).
//!
//! A [Profile] collects these raw attribute values, keyed by kind.
//! [Hardening](Profile::harden) a `Profile` produces a [Fingerprint], in which
//! every attribute value has been hashed with Argon2, and the resulting
//! keyspace carries a proof-of-work constraint for later use.
//!
//! Cryptographic keys are derived from a `Fingerprint` by [selecting](attrkey)
//! a subset of special attributes. The selected and remaining attribute values
//! are bound into an [annihilative pair](https://docs.rs/annihilation/) under
//! the fingerprint's proof-of-work constraint, so each distinct selection
//! yields an independent key: knowledge of the key for one selection gives no
//! advantage in deriving the key for another.
//!
//! # Confirmation
//!
//! Before committing to a selection, [confirming](Fingerprint::confirm)
//! produces a [Confirmation]: a short, human-readable code paired with the
//! special attribute selection it covers. The code is a one-way digest of the
//! special attribute values it covers, so it can be displayed, compared, or
//! stored for confirmation of the selection without revealing the derived key
//! itself. Passing a `Confirmation` to the fingerprint
//! [derive_key](Fingerprint::derive_key) method recomputes and checks its code
//! against the stored selection before deriving, guarding against tampering
//! or mismatch.
//!
//! # Features
//!
//! With the `unchecked` feature, keys can be derived directly from a special
//! attribute selection, skipping the [Confirmation] tamper check via:
//! - The [derive_key_unchecked](Fingerprint::derive_key_unchecked) method
//! to derive a key.
//! - The [derive_key_into_unchecked](Fingerprint::derive_key_into_unchecked)
//! method to derive a key into a provided buffer.
//!
//! # Example
//! ```
//! use human_key::{Attribute, Params, Profile};
//!
//! fn main() {
//!     let profile = [
//!         (Attribute::Name, b"MUSTERMANN".to_vec()),
//!         (Attribute::GivenName, b"ERIKA".to_vec()),
//!         (Attribute::BirthName, b"GABLER".to_vec()),
//!         (Attribute::DateOfBirth, b"12.08.1964".to_vec()),
//!         (Attribute::Nationality, b"DEUTSCH".to_vec()),
//!         (Attribute::CityOfBirth, b"BERLIN".to_vec()),
//!         (Attribute::EyeColor, b"GREEN".to_vec()),
//!         (Attribute::Height, b"160CM".to_vec()),
//!     ]
//!     .into_iter()
//!     .collect::<Profile<Attribute>>();
//!
//!     // Harden the profile into a fingerprint using the default params
//!     let params = Params::default();
//!     let fingerprint = profile
//!         .harden(&params)
//!         .expect("profile and valid params should harden into fingerprint");
//!
//!     // Confirm two special attribute selections in the same fingerprint
//!     let selection_1 = [Attribute::Name, Attribute::EyeColor];
//!     let selection_2 = [Attribute::DateOfBirth, Attribute::Nationality];
//!
//!     let confirmation_1 = fingerprint
//!         .confirm(&selection_1)
//!         .expect("attributes in profile should be selectable for confirmation");
//!     let confirmation_2 = fingerprint
//!         .confirm(&selection_2)
//!         .expect("attributes in profile should be selectable for confirmation");
//!
//!     // Derive keys from fingerprints using each confirmation
//!     let dk = fingerprint
//!         .derive_key(&confirmation_1, None)
//!         .expect("confirmation is valid");
//!
//!     let mut dst = [0u8; 32];
//!     fingerprint
//!         .derive_key_into(&confirmation_2, &mut dst)
//!         .expect("confirmation is valid");
//!
//!     // Different special attribute selections produce different keys
//!     assert_ne!(dk, dst);
//! }
//! ```
mod attributes;
mod derivation;
mod errors;
mod params;

pub use crate::attributes::{Attribute, AttributeKind};
pub use crate::derivation::{
    CROCKFORD_BASE32, Confirmation, Fingerprint, Profile,
};
pub use crate::errors::HkErr;
pub use crate::params::Params;