# 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.
* [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 (Current)](#v020-current)
* [v0.3.0 (Planned - Possible Breaking Changes)](#v030-planned---possible-breaking-changes)
* [v0.4.0 (Planned - Possible Breaking Changes)](#v040-planned---possible-breaking-changes)
* [v0.5.0 (Planned - Possible Breaking Changes)](#v050-planned---possible-breaking-changes)
* [v0.6.0 (Planned - Possible Breaking Changes)](#v060-planned---possible-breaking-changes)
* [v1.0.0 (Future)](#v100-future)
* [Security Model](#security-model)
* [License](#license)
## 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
| `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
```toml
[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](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
> **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:
- [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 - Current)
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 (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
- **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.
**Planned**:
- **Constant-time utilities** - Timing attack resistance for cryptographic operations (comparison, equality checks)
**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** (planned): Will be 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
- 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.