byte-array-ops 0.2.1

A no_std-compatible library for ergonomic byte array operations with optional security hardening. Supports multiple input formats (hex, binary, UTF-8), bitwise operations, and comprehensive type conversions with minimal dependencies.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

# byte-array-ops

> **IMPORTANT: Crate Split in v0.3.0**
>
> Starting with v0.3.0, security hardening features will be moved to a separate crate. This crate will remain focused on general-purpose byte array operations. See the [Security Hardening](#security-hardening) section for details.

**Active Development Warning**
This library is under heavy active development. Core functionality (type conversions, bitwise operations) is stable and production ready.

## 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 |
| `ops_simd`     | SIMD-optimized operations              | No      | Planned     | 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 features**: Moved to a separate crate in v0.3.0 - see [Security Hardening](#security-hardening) section

## Installation

```toml,no_run
[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](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 (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:
- [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 (Current)
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 (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

## Security Hardening

**As of v0.3.0, security hardening features have been moved to a separate crate.**

### Why the Split?

Due to inherent design requirements, secure and general-purpose byte array operations cannot coexist in the same crate without maintenance issues:

**Technical Constraints:**
- **Additive features requirement**: Rust features should be additive to avoid breaking changes upon feature activation/deactivation
- **Type divergence**: Constant-time operations require different types and function signatures that are incompatible with general-purpose use
- **API restrictions**: General-purpose use needs to deref `Vec<_>` to access standard methods, but secure versions must restrict these due to reallocation and data remnants concerns
- **Security guarantees**: Hardened types cannot provide all standard `Vec` operations without compromising security

### Migration Path

**Current users (v0.2.x):**
- This crate (`byte-array-ops`) will continue as a general-purpose byte array library
- No action needed for general-purpose use cases

**Users needing security hardening:**
- Security features (zeroize, constant-time ops, memory locking, memory encryption) will be available in a separate crate starting v0.3.0
- The secure crate will depend on this crate for core functionality
- Documentation for the secure crate will be provided upon release

For historical reference on planned security features, see [`archive/security_features.md`](archive/security_features.md).

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](https://gitlab.com/jurassicLizard/byte-array-ops/-/blob/master/LICENSE) for details.