byte-array-ops 0.1.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

# byte-array-ops

⚠️ **Active Development Warning**
This library is under heavy active development. Core functionality (type conversions, bitwise operations) is stable and production-ready. Security-hardening features are planned for v0.2.0+.

## 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 |
| `sec_basic_hardening`       | Basic security tier (zeroize on drop)        | ❌ No    | ⏳ Planned (v0.2.0) | Handling sensitive data like keys, passwords                    |
| `sec_enhanced_hardening`    | Enhanced security (const-time ops + memlock) | ❌ No    | ⏳ Planned (v0.2.0) | Cryptographic operations, preventing timing attacks             |
| `sec_maximum_hardening`     | Maximum security (all features + memencrypt) | ❌ No    | ⏳ Planned (v0.2.0) | High-security environments, defense in depth                    |
| `sec_harden_zeroize`        | Secure memory wiping                         | ❌ No    | ⏳ Planned          | Use tiers instead (individual feature for advanced users)       |
| `sec_harden_const_time_ops` | Constant-time comparisons                    | ❌ No    | ⏳ Planned          | Use tiers instead (individual feature for advanced users)       |
| `sec_harden_memlock`        | Memory locking (prevent swap to disk)        | ❌ No    | ⏳ Planned          | Use tiers instead (individual feature for advanced users)       |
| `sec_harden_memencrypt`     | In-memory encryption                         | ❌ No    | ⏳ Planned          | Use tiers instead (individual feature for advanced users)       |
| `ops_simd`                  | SIMD-optimized operations                    | ❌ No    | ⏳ Planned (v0.3.0) | 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 tiers**: Use when handling sensitive data (choose appropriate tier for your threat model)
- **Individual security features**: For fine-grained control (advanced users only)

## Installation

```toml
[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
- Using the builder pattern

### Basic Example

```rust
use byte_array_ops::ByteArray;
use byte_array_ops::errors::ByteArrayError;

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

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

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

### v0.1.0 (Current)
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 (Planned)
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

### v0.3.0 (Planned)
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

## License

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