byte-array-ops 0.3.0

A no_std-compatible library for security-by-default byte array operations. Includes automatic memory zeroization, constant-time utilities, multiple input formats (hex, binary, UTF-8), bitwise operations, and comprehensive type conversions with minimal dependencies.
Documentation

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

Feature Purpose Default Status Use Cases
ops_simd SIMD-optimized operations No Planned High-performance bulk operations
experimental Unstable/experimental features No Ongoing Development 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]);
    
    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)
  • Hardened constructors and secure reallocation
  • Bugfixes and refinements

v0.4.0 (Planned - Possible Breaking Changes)

Security hardening for cryptographic and sensitive data use cases:

  • Constant-time operations (timing attack prevention)
  • Bugfixes and refinements

v0.5.0 (Planned - Possible Breaking Changes)

Security hardening for cryptographic and sensitive data use cases:

  • Memory locking (prevent swapping to disk)
  • Bugfixes and refinements

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.