Module usage_notes

byte_array_ops

Module usage_notes 

Source
Expand description

Repository readme mirror

§byte-array-ops

Active Development Warning This library is under active development. Starting with v0.3.0, this crate adopts a security-by-default approach with automatic memory zeroization and constant-time utilities always enabled. Core functionality (type conversions, bitwise operations) is stable and production-ready.

§Overview

A no_std-compatible Rust library for secure-by-default byte array operations.

Design Philosophy:

  • Security by default - Essential protections (memory zeroization, constant-time utilities) are always compiled in. No opt-in needed for safety when handling cryptographic material.
  • Minimal dependencies - Only what’s necessary for security and functionality. Fast compilation, small binary footprint (zeroize + subtle add ~10KB).
  • Test-driven development - Comprehensive test coverage for all features. Experimental features are gated behind the experimental flag (disabled by default).

§Features

FeaturePurposeDefaultStatusUse Cases
ops_simdSIMD-optimized operationsNoPlannedHigh-performance bulk operations
experimentalUnstable/experimental featuresNoOngoingDevelopment and testing only

Security Features (Always Enabled):

  • Memory zeroization (zeroize) - Automatic cleanup on drop

Note on Feature Selection:

  • Core functionality: Type conversions and bitwise operations work out of the box
  • Security: Memory zeroization always enabled (not opt-in)

§Installation

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

# Security features (zeroize, constant-time ops) are always included
# For no_std environments with alloc
byte-array-ops = { version = "0.3", default-features = false }

§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
  • Convenience macros (try_bytes!, try_hex!, try_bin!)

CAVEAT: The try_bytes! macro silently converts to UTF-8 when no format prefix (0x, 0b, 0o) is provided. Use try_hex! or try_bin! for guaranteed hex/binary parsing without format detection.

§Basic Example

use byte_array_ops::ByteArray;
use byte_array_ops::errors::ByteArrayError;
use byte_array_ops::{try_hex, try_bin};

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

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

    // Using macros for convenience
    let with_macro = try_hex!("cafe")?;
    assert_eq!(with_macro.as_bytes(), [0xca, 0xfe]);

    let binary = try_bin!("11110000")?;
    assert_eq!(binary.as_bytes(), [0xf0]);

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

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

    // Range indexing
    let slice = &from_hex[1..3];      // bytes 1-2: [0xad, 0xbe]
    let tail = &from_hex[2..];        // from index 2 to end

    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 (Released)

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 (Released - Current)

Security-by-default architecture:

  • Automatic memory zeroization on drop
  • Remove security feature flags (always enabled)
  • Remove ops_algebra feature (operations always compiled)
  • Security-focused documentation

§v0.4.0 (Planned - Possible Breaking Changes)

Constant-time operations:

  • Constant-time equality and comparisons
  • Timing attack prevention
  • Audit operations for timing vulnerabilities

§v0.5.0 (Planned - Possible Breaking Changes)

Memory locking:

  • Prevent swapping to disk via mlock/munlock
  • Secure reallocation with memory locking
  • Platform-specific implementations

§v0.6.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

§Security Model

This library is designed with security-by-default:

Always Enabled:

  • Memory zeroization (zeroize) - Sensitive data is automatically cleared on drop
  • Constant-time utilities (subtle) - Timing attack resistance for cryptographic operations

Why Security-by-Default?

Most byte array operations in Rust involve cryptographic material (keys, IVs, authentication tokens, passwords). Making security opt-in creates a dangerous default where developers must remember to enable protections. Instead, we make the secure choice the easy choice.

What About Performance?

Security features add minimal overhead:

  • Zeroize: ~1-2% overhead on drop (only for sensitive data)
  • Constant-time ops: Used selectively for comparisons where timing attacks matter

For the vast majority of use cases, this overhead is negligible compared to the security guarantees provided. PENDING BENCHMARKS FOR LARGE BYTEARRAY

Best Practices:

  • Use this library for cryptographic material (keys, IVs, passwords, authentication tokens)
  • For general-purpose byte manipulation where security is not a concern, standard Vec<u8> may be more appropriate
  • Always review XOR encryption example warning (see documentation)
  • Memory zeroization helps but doesn’t prevent all attacks (core dumps, speculative execution, etc.)

Limitations:

  • Cannot prevent core dumps of live memory
  • No defense against speculative execution attacks
  • Memory must exist in plaintext during use
  • Zeroization occurs on drop, not during intermediate operations

§License

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