Crate byte_array_ops 

Welcome to the ByteArrayOps Library

Introduction

This is a no_std-compatible library designed for security-by-default byte array operations. Starting with v0.3.0, security features (memory zeroization, constant-time utilities) are always enabled. The library provides an ergonomic way to conduct operations on byte arrays for cryptographic and security-sensitive use cases.

Quick Start Examples

Creating ByteArrays - Multiple Ways

use byte_array_ops::ByteArray;
use byte_array_ops::errors::ByteArrayError;

fn main() -> Result<(), ByteArrayError> {
    // From hex string (with 0x prefix)
    let from_hex: ByteArray = "0xdeadbeef".parse()?;
    assert_eq!(from_hex.as_bytes(), [0xde, 0xad, 0xbe, 0xef]);

    // From binary string (with 0b prefix)
    let from_bin: ByteArray = "0b11110000".parse()?;
    assert_eq!(from_bin.as_bytes(), [0xf0]);

    // From UTF-8 string (no prefix)
    let from_utf8: ByteArray = "hello".parse()?;
    assert_eq!(from_utf8.as_bytes(), b"hello");

    // From byte slice using From trait
    let from_slice: ByteArray = [0x01, 0x02, 0x03].as_slice().into();
    assert_eq!(from_slice.len(), 3);

    // From `Vec<u8>` using From trait
    let from_vec: ByteArray = vec![0xaa, 0xbb, 0xcc].into();
    assert_eq!(from_vec.as_bytes(), [0xaa, 0xbb, 0xcc]);

    // From array literal using From trait
    let from_array: ByteArray = [0xff; 4].into();
    assert_eq!(from_array.as_bytes(), [0xff, 0xff, 0xff, 0xff]);

    // Using static constructor with hex
    let with_hex = ByteArray::from_hex("cafe")?;
    assert_eq!(with_hex.as_bytes(), [0xca, 0xfe]);

    // Using static constructor with binary
    let with_bin = ByteArray::from_bin("1010_0101")?;
    assert_eq!(with_bin.as_bytes(), [0xa5]);

    // NOTE: All ByteArray instances are automatically zeroized when dropped
    // to prevent sensitive data from remaining in memory.

    Ok(())
}

Macro Examples

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.

use byte_array_ops::{try_bytes, try_hex, try_bin, bytes};
use byte_array_ops::errors::ByteArrayError;

fn main() -> Result<(), ByteArrayError> {
    // try_bytes! - Parse with format detection (0x/0b prefix or UTF-8)
    let from_hex = try_bytes!("0xdeadbeef")?;
    assert_eq!(from_hex.as_bytes(), [0xde, 0xad, 0xbe, 0xef]);

    let from_bin = try_bytes!("0b11110000")?;
    assert_eq!(from_bin.as_bytes(), [0xf0]);

    // CAVEAT: No prefix = UTF-8 conversion!
    let from_utf8 = try_bytes!("hello")?;
    assert_eq!(from_utf8.as_bytes(), b"hello");

    // try_hex! - Always parses as hex (no UTF-8 fallback)
    let hex_only = try_hex!("cafe")?;
    assert_eq!(hex_only.as_bytes(), [0xca, 0xfe]);

    // try_bin! - Always parses as binary (no UTF-8 fallback)
    let bin_only = try_bin!("11110000")?;
    assert_eq!(bin_only.as_bytes(), [0xf0]);

    // bytes! - Initialize with repeated pattern (similar to vec![val; count])
    let repeated = bytes![0xff; 10];
    assert_eq!(repeated.len(), 10);
    assert_eq!(repeated.as_bytes(), [0xff; 10]);

    Ok(())
}

XOR Encryption Example

SECURITY WARNING: This example demonstrates XOR operations for educational purposes only. DO NOT use XOR for encryption in production. Use established encryption algorithms (AES-GCM, ChaCha20-Poly1305) from properly audited libraries.

use byte_array_ops::ByteArray;
use byte_array_ops::errors::ByteArrayError;

fn main() -> Result<(), ByteArrayError> {
    // Encrypt plaintext with a key using XOR
    let plaintext: ByteArray = "secret message".parse()?;
    let key: ByteArray = "0x_de_ad_be_ef_ca_fe_ba_be_01_02_03_04_05_06".parse()?;

    let mut cipher_out = vec![0u8; plaintext.len()];
    let encrypted_len = encrypt(plaintext.as_bytes(), key.as_bytes(), &mut cipher_out);

    assert_eq!(encrypted_len, plaintext.len());

    // Decrypt the ciphertext (XOR is symmetric)
    let mut decrypted_out = vec![0u8; encrypted_len];
    let decrypted_len = decrypt(&cipher_out[..encrypted_len], key.as_bytes(), &mut decrypted_out);

    assert_eq!(&decrypted_out[..decrypted_len], plaintext.as_bytes());

    // NOTE: plaintext, key, and result ByteArrays are automatically zeroized
    // when dropped to prevent sensitive data from remaining in memory.

    Ok(())
}

fn encrypt(input: &[u8], key: &[u8], output: &mut [u8]) -> usize {
    // Simple XOR encryption (NOT secure, for demonstration only!)
    let input_ba: ByteArray = input.into();
    let key_ba: ByteArray = key.into();
    let result = input_ba ^ key_ba;

    let bytes_written = result.len().min(output.len());
    output[..bytes_written].copy_from_slice(&result.as_bytes()[..bytes_written]);
    bytes_written
    // NOTE: input_ba, key_ba, and result are zeroized here when function returns
}

fn decrypt(input: &[u8], key: &[u8], output: &mut [u8]) -> usize {
    // XOR is symmetric, so decrypt is the same as encrypt
    encrypt(input, key, output)
}

Bitwise Operations

use byte_array_ops::ByteArray;



let a: ByteArray = "0xff00".parse().unwrap();
let b: ByteArray = "0x0ff0".parse().unwrap();

// XOR operation
let xor_result = a.clone() ^ b.clone();
assert_eq!(xor_result.as_bytes(), [0xf0, 0xf0]);

// AND operation
let and_result = a.clone() & b.clone();
assert_eq!(and_result.as_bytes(), [0x0f, 0x00]);

// OR operation
let or_result = a.clone() | b.clone();
assert_eq!(or_result.as_bytes(), [0xff, 0xf0]);

// NOT operation
let not_result = !a;
assert_eq!(not_result.as_bytes(), [0x00, 0xff]);

// NOTE: All ByteArrays (a, b, xor_result, and_result, or_result, not_result)
// are automatically zeroized when dropped.

Array Operations

use byte_array_ops::ByteArray;

fn main() -> Result<(), byte_array_ops::errors::ByteArrayError> {
    let mut arr: ByteArray = "0xdeadbeefcafe".parse()?;

    // Range indexing (immutable)
    assert_eq!(arr[1..3], [0xad, 0xbe]);
    assert_eq!(arr[2..], [0xbe, 0xef, 0xca, 0xfe]);
    assert_eq!(arr[..2], [0xde, 0xad]);
    assert_eq!(arr[1..=3], [0xad, 0xbe, 0xef]);

    // Range indexing (mutable)
    arr[0..2].copy_from_slice(&[0x00, 0x01]);
    assert_eq!(arr[0], 0x00);

    // Secure truncate (zeroizes discarded bytes)
    arr.truncate(3);
    assert_eq!(arr.len(), 3);

    Ok(())
}

Module Overview

This library is organized into the following modules:

• model - Core ByteArray type and constructors
• type_conv - Type conversion implementations (From, Into, FromStr)
• ops - Bitwise operations (XOR, AND, OR, NOT)
• iter - Iterator implementations
• errors - Error types for parsing and conversions
• macros - Declarative macros for easy ByteArray construction
• security - Security implementations (display, vec operations, zeroization)

Key Types

Core Types

• ByteArray - Main byte array type with automatic capacity management

Iterators

• ByteArrayIter - Immutable iterator over bytes
• ByteArrayIterMut - Mutable iterator over bytes

Error Types

• ByteArrayError - Errors during parsing and conversions

Trait Implementations

ByteArray implements many standard Rust traits for ergonomic usage:

Conversions:

• From<&[u8]>, From<Vec<u8>>, From<&Vec<u8>>, From<[u8; N]> - Create from bytes
• FromStr - Parse from strings (hex with 0x, binary with 0b, UTF-8 fallback)
• Into<Vec<u8>> - Extract underlying bytes (zero-cost move)
• AsRef<[u8]> - Borrow as byte slice

Operations:

• BitXor, BitXorAssign - XOR operations (^, ^=)
• BitAnd, BitAndAssign - AND operations (&, &=)
• BitOr, BitOrAssign - OR operations (|, |=)
• Not - NOT operation (!)

Iteration:

• IntoIterator - Iterate by reference (&ByteArray, &mut ByteArray)
• ExactSizeIterator - Iterators with known length

Comparison:

• PartialEq, Eq - Equality comparisons
• Clone - Cloning support
• Default - Default constructor (empty array)

Indexing:

• Index<usize>, IndexMut<usize> - Array-style indexing (arr[0], arr[1] = 0xff)

Implementation Notes

Feature Flags: Check Cargo.toml for optional features (ops_simd, experimental). Security features (zeroization, constant-time utilities) are always enabled starting with v0.3.0.

Security-by-Default: Security dependencies (zeroize, subtle) are now required dependencies. The trust module provides implementations focused on security while maintaining ergonomic use. See the [installation_notes][Readme Notes]

Re-exports

pub use model::ByteArray;

Modules

errors

This module encapsulates all errors that core can throw

iter

Iterator implementations for ByteArray

macros

model

This is the main model for our ByteArray Object

ops

security

type_conv

This module contains all type conversion definitions to and from ByteArray

usage_notes

Repository readme mirror

Macros

bytes

Macro to create a [ByteArray] with a value and a count similar to vec![val; count]

try_bin

Macro for creating a ByteArray from a binary string literal (without 0b prefix).

try_bytes

Macro for creating a ByteArray from a string literal with automatic format detection.

try_hex

Macro for creating a ByteArray from a hexadecimal string literal (without 0x prefix).