hctr2_rs/
lib.rs

1//! HCTR2 and HCTR3 length-preserving encryption library.
2//!
3//! This crate provides implementations of HCTR2 and HCTR3 wide-block tweakable ciphers,
4//! including their beyond-birthday-bound (BBB) secure variants and format-preserving modes.
5//!
6//! # Overview
7//!
8//! HCTR2 and HCTR3 are length-preserving encryption modes suitable for applications like:
9//! - Full-disk encryption
10//! - Filename encryption
11//! - Database field encryption
12//!
13//! # Variants
14//!
15//! - **HCTR2**: Standard HCTR2 with birthday-bound (~64-bit) security
16//! - **HCTR3**: Enhanced security with two-key construction and LFSR-based ELK mode
17//! - **CHCTR2**: Cascaded HCTR2 with ~85-bit multi-user security
18//! - **HCTR2-TwKD**: HCTR2 with tweak-based key derivation for BBB security
19//! - **HCTR2++**: HCTR2 with R3 fresh re-keying and a 2n-bit hash for BBB security
20//! - **HCTR2-FP/HCTR3-FP**: Format-preserving variants for encrypting structured data
21//!
22//! # Quick Start
23//!
24//! ## Basic HCTR2 encryption
25//!
26//! ```rust
27//! use hctr2_rs::Hctr2_128;
28//!
29//! let key = [0u8; 16];
30//! let cipher = Hctr2_128::new(&key);
31//!
32//! let plaintext = b"Hello, HCTR2 World!";
33//! let tweak = b"unique tweak";
34//!
35//! let mut ciphertext = vec![0u8; plaintext.len()];
36//! cipher.encrypt(plaintext, tweak, &mut ciphertext).unwrap();
37//!
38//! let mut decrypted = vec![0u8; plaintext.len()];
39//! cipher.decrypt(&ciphertext, tweak, &mut decrypted).unwrap();
40//! assert_eq!(plaintext.as_slice(), decrypted.as_slice());
41//! ```
42//!
43//! ## Format-preserving encryption (credit card numbers)
44//!
45//! ```rust
46//! use hctr2_rs::{Hctr2Fp_128_Decimal, encode_base_radix, first_block_length};
47//!
48//! let key = [0u8; 16];
49//! let cipher = Hctr2Fp_128_Decimal::new(&key);
50//!
51//! // 16-digit credit card number represented as individual digits
52//! // Note: minimum length for decimal is 39 digits (first_block_length(10))
53//! // For shorter inputs, use a different radix or padding scheme
54//! let first_len = first_block_length(10); // 39
55//! let mut cc_digits = vec![0u8; first_len + 1]; // 40 digits
56//! // Fill with some valid decimal digits (each must be 0-9)
57//! cc_digits[0] = 4; cc_digits[1] = 1; cc_digits[2] = 2; cc_digits[3] = 3;
58//!
59//! let tweak = b"merchant_id_123";
60//! let mut encrypted = vec![0u8; cc_digits.len()];
61//! cipher.encrypt(&cc_digits, tweak, &mut encrypted).unwrap();
62//!
63//! // All encrypted digits are still in range [0, 9]
64//! for &d in &encrypted {
65//!     assert!(d < 10);
66//! }
67//! ```
68//!
69//! # Security Considerations
70//!
71//! - **Never reuse (key, tweak) pairs**: Each encryption must use a unique tweak
72//! - **No authentication**: These are encryption-only modes; use AEAD for integrity
73//! - **Minimum message length**: 16 bytes for HCTR2/HCTR3, varies by radix for FP modes
74//!
75//! # Feature Flags
76//!
77//! - `std` (default): Enable standard library support
78//! - When disabled, the crate is `no_std` compatible
79
80#![cfg_attr(not(feature = "std"), no_std)]
81
82pub mod chctr2;
83pub mod common;
84pub mod hctr2;
85pub mod hctr2_twkd;
86pub mod hctr2fp;
87pub mod hctr2pp;
88pub mod hctr3;
89pub mod hctr3fp;
90
91#[cfg(test)]
92mod cross_check;
93
94#[allow(deprecated)]
95pub use chctr2::Chctr2Error;
96pub use chctr2::{Chctr2, Chctr2_128, Chctr2_256};
97pub use common::Error;
98#[allow(deprecated)]
99pub use hctr2::Hctr2Error;
100pub use hctr2::{AesCipher, Hctr2, Hctr2_128, Hctr2_256};
101#[allow(deprecated)]
102pub use hctr2_twkd::Hctr2TwKDError;
103pub use hctr2_twkd::{CencKdf128, CencKdf256, Hctr2TwKD_128, Hctr2TwKD_256};
104#[allow(deprecated)]
105pub use hctr2fp::Hctr2FpError;
106pub use hctr2fp::{
107    Hctr2Fp, Hctr2Fp_128_Base64, Hctr2Fp_128_Decimal, Hctr2Fp_128_Hex, Hctr2Fp_256_Base64,
108    Hctr2Fp_256_Decimal, Hctr2Fp_256_Hex, decode_base_radix, encode_base_radix, first_block_length,
109};
110pub use hctr2pp::{Hctr2pp, Hctr2pp_128, Hctr2pp_256};
111#[allow(deprecated)]
112pub use hctr3::Hctr3Error;
113pub use hctr3::{Hctr3, Hctr3_128, Hctr3_256};
114pub use hctr3fp::{
115    Hctr3Fp, Hctr3Fp_128_Base64, Hctr3Fp_128_Decimal, Hctr3Fp_128_Hex, Hctr3Fp_256_Base64,
116    Hctr3Fp_256_Decimal, Hctr3Fp_256_Hex,
117};
hctr2_rs/lib.rs

hctr2_rs/
lib.rs
