byte-array-ops

⚠️ Active Development Warning This library is under heavy active development. Core functionality (type conversions, bitwise operations) is stable and production-ready. Security-hardening features are planned for v0.2.0+.

Overview

A no_std-compatible Rust library for ergonomic byte array operations with optional security hardening.

Design Philosophy:

Compile only what you need - Feature flags for graceful degradation. Basic conversions work without any features, bitwise operations require ops_algebra (enabled by default), and security features are opt-in.
Minimal dependencies - Keep compilation fast and dependency tree small for a pleasant development experience.
Test-driven development - No functionality is added without comprehensive test coverage. Untested or experimental features are gated behind the experimental flag (disabled by default and guarded with compile_error!).

Features

Feature	Purpose	Default	Status	Use Cases
`ops_algebra`	Bitwise operations (XOR, AND, OR, NOT)	✅ Yes	✅ Implemented	Crypto implementations, data masking, general byte manipulation
`sec_basic_hardening`	Basic security tier (zeroize on drop)	❌ No	⏳ Planned (v0.2.0)	Handling sensitive data like keys, passwords
`sec_enhanced_hardening`	Enhanced security (const-time ops + memlock)	❌ No	⏳ Planned (v0.2.0)	Cryptographic operations, preventing timing attacks
`sec_maximum_hardening`	Maximum security (all features + memencrypt)	❌ No	⏳ Planned (v0.2.0)	High-security environments, defense in depth
`sec_harden_zeroize`	Secure memory wiping	❌ No	⏳ Planned	Use tiers instead (individual feature for advanced users)
`sec_harden_const_time_ops`	Constant-time comparisons	❌ No	⏳ Planned	Use tiers instead (individual feature for advanced users)
`sec_harden_memlock`	Memory locking (prevent swap to disk)	❌ No	⏳ Planned	Use tiers instead (individual feature for advanced users)
`sec_harden_memencrypt`	In-memory encryption	❌ No	⏳ Planned	Use tiers instead (individual feature for advanced users)
`ops_simd`	SIMD-optimized operations	❌ No	⏳ Planned (v0.3.0)	High-performance bulk operations
`experimental`	Unstable/experimental features	❌ No	🧪 Ongoing	Development and testing only

Note on Feature Selection:

No features needed: Simple conversions (hex ↔ bytes, UTF-8 ↔ bytes) work with default-features = false
ops_algebra (default): Enabled by default for bitwise operations
Security tiers: Use when handling sensitive data (choose appropriate tier for your threat model)
Individual security features: For fine-grained control (advanced users only)

Installation

[dependencies]
byte-array-ops = "0.1.0"

# Or disable default features for minimal build (conversions only)
byte-array-ops = { version = "0.1.0", default-features = false }

# For no_std environments with alloc and operations
byte-array-ops = { version = "0.1.0", default-features = false, features = ["ops_algebra"] }

Quick Start

See the API documentation for comprehensive examples including:

Creating ByteArrays from hex, binary, UTF-8, and raw bytes
Bitwise operations (XOR, AND, OR, NOT)
Working with iterators
Using the builder pattern

Basic Example

use byte_array_ops::ByteArray;
use byte_array_ops::errors::ByteArrayError;

fn main() -> Result<(),ByteArrayError> {

    // From hex string
    let from_hex: ByteArray = "0xdeadbeef".parse()?;
    assert_eq!(from_hex.as_bytes(), [0xde, 0xad, 0xbe, 0xef]);

    // From UTF-8 string (no prefix)
    let from_utf8: ByteArray = "hello".parse()?;
    assert_eq!(from_utf8.as_bytes(), b"hello");

    // Bitwise operations (requires ops_algebra feature)
    let a: ByteArray = "0xff00".parse()?;
    let b: ByteArray = "0x0ff0".parse()?;
    let result = a ^ b; // XOR
    assert_eq!(result.as_bytes(), [0xf0, 0xf0]);
    
    Ok(())
}

`no_std` Support

This library is no_std compatible and requires only the alloc crate. Perfect for:

Embedded systems with allocators (ESP32, ARM Cortex-M with heap)
Bootloaders and kernel development
WebAssembly environments
Any environment where std is unavailable

Roadmap

Note on version stability: All versions post-0.2.0 are subject to change depending on whether breaking changes are necessary in previous versions. When no more breaking API changes are planned, the "Active Development Warning" banner above will be removed. This is expected to happen well before v1.0.0 as the API matures for ergonomic use.

v0.1.0 (Old Milestone)

Core functionality with production-ready type conversions and bitwise operations:

✅ Multiple input formats (hex, binary, UTF-8, raw bytes)
✅ Bitwise operations (XOR, AND, OR, NOT)
✅ Comprehensive iterator support
✅ no_std compatibility with alloc

v0.2.0 (Current)

API refinement and macro ergonomics:

Cleanup API and experiment with most efficient (and most used) APIs
Lay the groundwork for introducing the SecureReallocationProvider trait, which will encompass more secure implementations of vector methods that may require allocation
Introduce helper macros for ByteArray construction

v0.3.0 (Planned - Possible Breaking Changes)

Security hardening for cryptographic and sensitive data use cases:

Secure memory wiping (zeroize on drop)
Memory locking (prevent swapping to disk)
Constant-time operations (timing attack prevention)
Hardened constructors and secure reallocation
Bugfixes and refinements

v0.4.0 (Planned - Possible Breaking Changes)

Performance optimization for high-throughput scenarios:

SIMD-accelerated bitwise operations
Benchmark suite and regression testing
Performance tuning for large arrays

v1.0.0 (Future)

Stable API with long-term compatibility guarantees:

API freeze after real-world usage validation
Security audit (if feasible - even major libraries like RustCrypto often lack formal audits)
Comprehensive test coverage and fuzzing
Multi-platform testing and verification

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

byte-array-ops 0.2.0