Crate promocrypt_core

Crate promocrypt_core 

Source
Expand description

§promocrypt-core

Core library for cryptographically secure promotional code generation.

§Features

  • HMAC-SHA256 code generation - Cryptographically secure codes
  • Damm check digit - 100% detection of single errors and transpositions
  • Two-key encryption - MachineID for read, secret for write
  • Machine binding - .bin files can be bound to specific machines
  • Multiple counter modes - File, in-bin, manual, or external
  • FFI ready - C-compatible interface for other languages

§Quick Start

use promocrypt_core::{BinFile, BinConfig, CounterMode, create_config};

// Create a new .bin file
let mut config = create_config("production");
config.counter_mode = CounterMode::InBin;

let mut bin = BinFile::create("production.bin", "my-secret", config).unwrap();

// Generate codes
let codes = bin.generate_batch(1000).unwrap();

// Validate codes
for code in &codes {
    assert!(bin.is_valid(code));
}

§Two-Key System

Each .bin file uses a two-key encryption system:

  • MachineID: Derived from hardware identifiers, allows read-only access (validation, reading config)
  • Secret: User-provided password, allows full access (generation, mastering, configuration changes)
use promocrypt_core::BinFile;

// Open read-only with machineID (automatic)
let bin = BinFile::open_readonly("production.bin").unwrap();
assert!(bin.validate("SOMECODE").is_valid() || !bin.validate("SOMECODE").is_valid());

// Open with full access using secret
let mut bin = BinFile::open_with_secret("production.bin", "my-secret").unwrap();
let code = bin.generate().unwrap();

§Counter Modes

  • CounterMode::File { path } - Counter in separate file with OS locking
  • CounterMode::InBin - Counter in .bin mutable section
  • CounterMode::Manual - Caller provides counter values
  • CounterMode::External - Consumer manages counter (e.g., database)

Re-exports§

pub use alphabet::Alphabet;
pub use alphabet::DEFAULT_ALPHABET;
pub use alphabet::default_alphabet;
pub use alphabet::validate_alphabet;
pub use audit::AuditInfo;
pub use audit::ConfigChange;
pub use audit::GenerationLogEntry;
pub use audit::History;
pub use audit::MachineMastering;
pub use audit::SecretRotation;
pub use binary_file::AccessLevel;
pub use binary_file::BinConfig;
pub use binary_file::BinFile;
pub use binary_file::BinStats;
pub use binary_file::create_config;
pub use counter::CounterMode;
pub use damm::DammTable;
pub use error::ErrorCode;
pub use error::PromocryptError;
pub use error::Result;
pub use error::ValidationResult;
pub use generator::CheckPosition;
pub use generator::CodeFormat;
pub use generator::CodeGenerator;
pub use generator::generate_batch;
pub use generator::generate_code;
pub use machine_id::get_machine_id;
pub use machine_id::is_machine_id_available;
pub use validator::is_valid;
pub use validator::validate;

Modules§

alphabet
Alphabet handling for promotional codes.
audit
Audit trail for tracking .bin file history.
binary_file
Binary file format handling for .bin files.
counter
Counter management for promotional code generation.
damm
Damm check digit algorithm.
encryption
Cryptographic operations for promocrypt-core.
error
Error types for promocrypt-core.
generator
Code generation using HMAC-SHA256.
machine_id
Machine identification for hardware binding.
validator
Code validation module.

Constants§

VERSION
Library version.

Functions§

generate_code_standalone
Generate a code with standalone parameters.
validate_code
Validate a code without opening a .bin file.