byte-array-ops 0.4.0

# byte-array-ops

**Notice**
Minimal functional milestones have been reached. No further features planned due to lack of priority. Security patches will be provided when needed for all versions


<!-- TOC -->
* [byte-array-ops](#byte-array-ops)
  * [Overview](#overview)
  * [Features](#features)
  * [Installation](#installation)
  * [Quick Start](#quick-start)
    * [Basic Example](#basic-example)
  * [`no_std` Support](#no_std-support)
  * [Roadmap](#roadmap)
    * [v0.1.0 (Old Milestone)](#v010-old-milestone)
    * [v0.2.0 (Released)](#v020-released)
    * [v0.3.0 (Released)](#v030-released)
    * [v0.4.0 (Released – Current)](#v040-released--current)
  * [Security Model](#security-model)
  * [License](#license)
<!-- TOC -->

## 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

**Security Features (Always Enabled)**:
- **Memory zeroization** (`zeroize`) - Automatic cleanup on drop
- **Constant-time utilities** (`subtle`) - Timing attack resistance for equality and bitwise operations

**Note on Feature Selection:**
- **Core functionality**: Type conversions and bitwise operations work out of the box
- **Security**: Memory zeroization and constant-time utilities always enabled (not opt-in)

## Installation

```toml
[dependencies]
byte-array-ops = "0.4"
```

## Quick Start

See the [API documentation](https://docs.rs/byte-array-ops) 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

```rust
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

> **Maintenance Mode:** This project has reached its minimal functional milestones and is now in maintenance mode. Security patches will be provided as needed. No new features are planned.

### v0.1.0 (Old Milestone)
Core functionality with production-ready type conversions and bitwise operations:
- [x] Multiple input formats (hex, binary, UTF-8, raw bytes)
- [x] Bitwise operations (XOR, AND, OR, NOT)
- [x] Comprehensive iterator support
- [x] no_std compatibility with alloc

### v0.2.0 (Released)
API refinement and macro ergonomics:
- [x] Cleanup API and experiment with most efficient (and most used) APIs
- [x] Lay the groundwork for introducing the `SecureReallocationProvider` trait, which will encompass more secure implementations of vector methods that may require allocation
- [x] Introduce helper macros for `ByteArray` construction

### v0.3.0 (Released)
Security-by-default architecture:
- [x] Automatic memory zeroization on drop
- [x] Remove security feature flags (always enabled)
- [x] Remove ops_algebra feature (operations always compiled)
- [x] Security-focused documentation

### v0.4.0 (Released – Current)
Constant-time operations:
- [x] Constant-time equality (`PartialEq`, `Eq`)
- [x] Constant-time bitwise operations (`XOR`, `AND`, `OR`)
- [x] Timing attack prevention for cryptographic use cases

~~### v0.5.0 (Planned - Possible Breaking Changes)~~ Deprioritized due to maintenance-mode
Memory locking:
- Prevent swapping to disk via mlock/munlock
- Secure reallocation with memory locking
- Platform-specific implementations

~~### v0.6.0 (Planned - Possible Breaking Changes)~~ Deprioritized due to maintenance-mode
Performance optimization for high-throughput scenarios:
- SIMD-accelerated bitwise operations
- Benchmark suite and regression testing
- Performance tuning for large arrays

~~### v1.0.0 (Future)~~ Deprioritized due to maintenance-mode
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 operations** (`subtle`) - Timing attack resistance for equality checks and bitwise operations (XOR, AND, OR)
- **Reallocation safety** - Methods that may trigger reallocation (e.g., `try_extend`) actively detect unsafe memory operations by tracking buffer addresses. If an unexpected reallocation occurs that could leave sensitive data remnants in the old memory location, these operations fail with a security error rather than silently leaking data.

**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)
- **Reallocation checks**: Negligible overhead (pointer comparison only)
- **Constant-time ops**: 2-3x slower than non-constant-time for bitwise operations, but necessary for cryptographic security

For the vast majority of use cases, this overhead is negligible compared to the security guarantees provided.

**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
- 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](https://gitlab.com/jurassicLizard/byte-array-ops/-/blob/master/LICENSE) for details.