Struct BinFile 

pub struct BinFile { /* private fields */ }

Handle to an opened .bin file.

Implementations

impl BinFile

pub fn create( path: impl AsRef<Path>, secret: &str, config: BinConfig, ) -> Result<Self>

Create a new .bin file.

Arguments

• path - File path for the new .bin file
• secret - Secret password for accessing the file
• config - Configuration for the .bin file

Example

use promocrypt_core::{BinFile, BinConfig, Alphabet, CheckPosition, CounterMode, AuditInfo, CodeFormat};

let config = BinConfig {
    name: "production".to_string(),
    alphabet: Alphabet::default_alphabet(),
    code_length: 9,
    check_position: CheckPosition::End,
    secret_key: String::new(), // Will be generated
    storage_key: String::new(), // Will be generated
    storage_encryption_enabled: false,
    damm_table: promocrypt_core::DammTable::new(26),
    counter_mode: CounterMode::Manual,
    format: CodeFormat::default(),
    audit: AuditInfo::default(),
};

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

pub fn create_in_memory(secret: &str, config: BinConfig) -> Result<Vec<u8>>

Create .bin in memory (for database storage).

pub fn open_readonly(path: impl AsRef<Path>) -> Result<Self>

Open with machineID (read-only access).

pub fn open_with_secret(path: impl AsRef<Path>, secret: &str) -> Result<Self>

Open with secret (full access).

pub fn from_bytes_readonly(data: &[u8]) -> Result<Self>

Open from bytes with machineID (read-only access).

pub fn from_bytes_with_secret(data: &[u8], secret: &str) -> Result<Self>

Open from bytes with secret (full access).

pub fn try_open_readonly(path: impl AsRef<Path>) -> Option<Self>

Try to open with machineID, returns None on any error.

pub fn try_open_with_secret( path: impl AsRef<Path>, secret: &str, ) -> Option<Self>

Try to open with secret, returns None on any error.

pub fn config(&self) -> &BinConfig

Get configuration (both access levels).

pub fn name(&self) -> &str

Get name.

pub fn alphabet(&self) -> &Alphabet

Get alphabet.

pub fn code_length(&self) -> usize

Get code length (without check digit).

pub fn total_length(&self) -> usize

Get total code length (with check digit).

pub fn check_position(&self) -> CheckPosition

Get check position.

pub fn counter_mode(&self) -> &CounterMode

Get counter mode.

pub fn audit(&self) -> &AuditInfo

Get audit info (both access levels).

pub fn access_level(&self) -> AccessLevel

Get access level.

pub fn is_bound(&self) -> bool

Check if file is bound to a machine.

pub fn format(&self) -> &CodeFormat

Get code format.

pub fn is_storage_encryption_enabled(&self) -> bool

Check if storage encryption is enabled.

pub fn get_history(&self) -> &History

Get history.

pub fn get_generation_log(&self) -> &[GenerationLogEntry]

Get generation log.

pub fn total_codes_generated(&self) -> u64

Get total codes generated.

pub fn validate(&self, code: &str) -> ValidationResult

Validate a code (both access levels). Handles formatted codes by stripping prefix/suffix/separators.

pub fn is_valid(&self, code: &str) -> bool

Quick validation check.

pub fn validate_batch(&self, codes: &[&str]) -> Vec<ValidationResult>

Validate multiple codes at once.

pub fn generate(&mut self) -> Result<String>

Generate a single code (requires FullAccess). Returns formatted code with prefix/suffix/separators if configured. If storage_encryption_enabled, returns encrypted code.

pub fn generate_batch(&mut self, count: usize) -> Result<Vec<String>>

Generate batch of codes (requires FullAccess).

pub fn generate_at(&self, counter: u64) -> Result<String>

Generate code at specific counter (doesn’t update counter).

pub fn generate_batch_at( &self, start_counter: u64, count: usize, ) -> Result<Vec<String>>

Generate batch at specific counter (doesn’t update counter).

pub fn get_counter(&self) -> Result<u64>

Get current counter value.

pub fn master_for_machine( &self, output_path: impl AsRef<Path>, target_machine_id: &[u8; 32], ) -> Result<()>

Master for a new machine (requires FullAccess).

pub fn export_unbound(&self, output_path: impl AsRef<Path>) -> Result<()>

Export unbound copy (requires FullAccess).

pub fn encrypt_code(&self, code: &str) -> Result<String>

Encrypt a code for database storage (requires FullAccess).

pub fn decrypt_code(&self, encrypted: &str) -> Result<String>

Decrypt a code from database storage (requires FullAccess).

pub fn encrypt_codes(&self, codes: &[&str]) -> Result<Vec<String>>

Encrypt multiple codes for storage (requires FullAccess).

pub fn decrypt_codes(&self, encrypted: &[&str]) -> Result<Vec<String>>

Decrypt multiple codes from storage (requires FullAccess).

pub fn set_storage_encryption(&mut self, enabled: bool) -> Result<()>

Enable or disable storage encryption (requires FullAccess).

pub fn set_counter_mode(&mut self, mode: CounterMode) -> Result<()>

Update counter mode (requires FullAccess).

pub fn set_format(&mut self, format: CodeFormat) -> Result<()>

Update code format (requires FullAccess).

pub fn set_check_position(&mut self, position: CheckPosition) -> Result<()>

Update check position (requires FullAccess).

pub fn set_prefix(&mut self, prefix: Option<String>) -> Result<()>

Set code prefix (requires FullAccess).

Arguments

• prefix - Optional prefix to prepend to generated codes

pub fn set_suffix(&mut self, suffix: Option<String>) -> Result<()>

Set code suffix (requires FullAccess).

Arguments

• suffix - Optional suffix to append to generated codes

pub fn set_separator(&mut self, separator: Option<char>) -> Result<()>

Set separator character (requires FullAccess).

Arguments

• separator - Optional separator character to insert at specified positions

pub fn set_separator_positions(&mut self, positions: Vec<usize>) -> Result<()>

Set separator positions (requires FullAccess).

Arguments

• positions - Positions where separator should be inserted (0-based, before the character)

pub fn save(&mut self) -> Result<()>

Save all configuration changes to the .bin file (requires FullAccess).

This persists all in-memory configuration changes to disk, including:

• Format changes (prefix, suffix, separator, separator_positions)
• Check position changes
• Storage encryption changes
• Counter mode changes
• History and generation log updates

Errors

Returns an error if:

• Access level is not FullAccess
• No file path is associated (in-memory file)
• IO error during write

pub fn rotate_secret( &mut self, old_secret: &str, new_secret: &str, ) -> Result<()>

Rotate the secret password (requires FullAccess). Re-encrypts the data_key with the new secret.

pub fn export_history(&self) -> String

Export history as JSON.

pub fn export_generation_log(&self) -> String

Export generation log as JSON.

pub fn clear_history(&mut self, keep_last: Option<usize>) -> Result<()>

Clear history (requires FullAccess).

pub fn clear_generation_log(&mut self, keep_last: Option<usize>) -> Result<()>

Clear generation log (requires FullAccess).

pub fn get_stats(&self) -> BinStats

Get statistics about this .bin file.