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

hctr2_rs/
lib.rs
