Crate hctr2_rs 

HCTR2 and HCTR3 length-preserving encryption library.

This crate provides implementations of HCTR2 and HCTR3 wide-block tweakable ciphers, including their beyond-birthday-bound (BBB) secure variants and format-preserving modes.

Overview

HCTR2 and HCTR3 are length-preserving encryption modes suitable for applications like:

• Full-disk encryption
• Filename encryption
• Database field encryption

Variants

• HCTR2: Standard HCTR2 with birthday-bound (~64-bit) security
• HCTR3: Enhanced security with two-key construction and LFSR-based ELK mode
• CHCTR2: Cascaded HCTR2 with ~85-bit multi-user security
• HCTR2-TwKD: HCTR2 with tweak-based key derivation for BBB security
• HCTR2-FP/HCTR3-FP: Format-preserving variants for encrypting structured data

Quick Start

Basic HCTR2 encryption

use hctr2::Hctr2_128;

let key = [0u8; 16];
let cipher = Hctr2_128::new(&key);

let plaintext = b"Hello, HCTR2 World!";
let tweak = b"unique tweak";

let mut ciphertext = vec![0u8; plaintext.len()];
cipher.encrypt(plaintext, tweak, &mut ciphertext).unwrap();

let mut decrypted = vec![0u8; plaintext.len()];
cipher.decrypt(&ciphertext, tweak, &mut decrypted).unwrap();
assert_eq!(plaintext.as_slice(), decrypted.as_slice());

Format-preserving encryption (credit card numbers)

use hctr2::{Hctr2Fp_128_Decimal, encode_base_radix, first_block_length};

let key = [0u8; 16];
let cipher = Hctr2Fp_128_Decimal::new(&key);

// 16-digit credit card number represented as individual digits
// Note: minimum length for decimal is 39 digits (first_block_length(10))
// For shorter inputs, use a different radix or padding scheme
let first_len = first_block_length(10); // 39
let mut cc_digits = vec![0u8; first_len + 1]; // 40 digits
// Fill with some valid decimal digits (each must be 0-9)
cc_digits[0] = 4; cc_digits[1] = 1; cc_digits[2] = 2; cc_digits[3] = 3;

let tweak = b"merchant_id_123";
let mut encrypted = vec![0u8; cc_digits.len()];
cipher.encrypt(&cc_digits, tweak, &mut encrypted).unwrap();

// All encrypted digits are still in range [0, 9]
for &d in &encrypted {
    assert!(d < 10);
}

Security Considerations

• Never reuse (key, tweak) pairs: Each encryption must use a unique tweak
• No authentication: These are encryption-only modes; use AEAD for integrity
• Minimum message length: 16 bytes for HCTR2/HCTR3, varies by radix for FP modes

Feature Flags

• std (default): Enable standard library support
• When disabled, the crate is no_std compatible

Re-exports

pub use chctr2::Chctr2Error;Deprecated

pub use chctr2::Chctr2;

pub use chctr2::Chctr2_128;

pub use chctr2::Chctr2_256;

pub use common::Error;

pub use hctr2::Hctr2Error;Deprecated

pub use hctr2::AesCipher;

pub use hctr2::Hctr2;

pub use hctr2::Hctr2_128;

pub use hctr2::Hctr2_256;

pub use hctr2_twkd::Hctr2TwKDError;Deprecated

pub use hctr2_twkd::CencKdf128;

pub use hctr2_twkd::CencKdf256;

pub use hctr2_twkd::Hctr2TwKD_128;

pub use hctr2_twkd::Hctr2TwKD_256;

pub use hctr2fp::Hctr2FpError;Deprecated

pub use hctr2fp::Hctr2Fp;

pub use hctr2fp::Hctr2Fp_128_Base64;

pub use hctr2fp::Hctr2Fp_128_Decimal;

pub use hctr2fp::Hctr2Fp_128_Hex;

pub use hctr2fp::Hctr2Fp_256_Base64;

pub use hctr2fp::Hctr2Fp_256_Decimal;

pub use hctr2fp::Hctr2Fp_256_Hex;

pub use hctr2fp::decode_base_radix;

pub use hctr2fp::encode_base_radix;

pub use hctr2fp::first_block_length;

pub use hctr3::Hctr3Error;Deprecated

pub use hctr3::Hctr3;

pub use hctr3::Hctr3_128;

pub use hctr3::Hctr3_256;

pub use hctr3fp::Hctr3Fp;

pub use hctr3fp::Hctr3Fp_128_Base64;

pub use hctr3fp::Hctr3Fp_128_Decimal;

pub use hctr3fp::Hctr3Fp_128_Hex;

pub use hctr3fp::Hctr3Fp_256_Base64;

pub use hctr3fp::Hctr3Fp_256_Decimal;

pub use hctr3fp::Hctr3Fp_256_Hex;

Modules

chctr2

CHCTR2 (Cascaded HCTR2) beyond-birthday-bound secure wide-block tweakable cipher.

common

Common utilities shared across HCTR2/HCTR3 cipher implementations.

hctr2

HCTR2 (Hash-CTR-Hash) length-preserving wide-block tweakable cipher.

hctr3

HCTR3 (Hash-CTR-Hash version 3) length-preserving wide-block tweakable cipher.

hctr2_twkd

HCTR2-TwKD (HCTR2 with Tweak-Based Key Derivation) beyond-birthday-bound secure cipher.

hctr2fp

HCTR2+FP (Format-Preserving) variant of HCTR2.

hctr3fp

HCTR3+FP (Format-Preserving) variant of HCTR3.