byte_array_ops/

lib.rs

//! Welcome to the ByteArrayOps Library
//!
//! # Introduction
//! This is a `no_std`-compatible library designed to provide an ergonomic and easy way to conduct operations on byte arrays.
//! It is intended both for general use where data sensitivity is not important and for cryptographic use cases or other cases
//! where privacy may be of concern.
//!
#![doc = include_str!("../README.md")]
//!
//! # 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]);
//!
//!     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};
//! 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]);
//!
//!     Ok(())
//! }
//! ```
//!
//! ## XOR Encryption Example
//!
//! ```
//! 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());
//!     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
//! }
//!
//! 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;
//!
//! fn main() {
//!     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]);
//! }
//! ```
//!
//! # Module Overview
//!
//! This library is organized into the following modules:
//! - [`core::model`](core::model) - Core [`ByteArray`] type and constructors
//! - [`core::type_conv`](core::type_conv) - Type conversion implementations (`From`, `Into`, `FromStr`)
//! - [`core::ops`](core::ops) - Bitwise operations (XOR, AND, OR, NOT) - requires `ops_algebra` feature
//! - [`core::iter`](core::iter) - Iterator implementations
//! - [`core::errors`](errors) - Error types for parsing and conversions
//! - [`core::macros`](macros) - Declarative macros for easy [`ByteArray`] construction
//! - `core::trust::hardened` - Security-hardened implementations (when hardening features enabled)
//! - `core::trust::insecure` - Convenience implementations (default mode)
//!
//! # Key Types
//!
//! ## Core Types
//! - [`ByteArray`] - Main byte array type with automatic capacity management
//!
//! ## Iterators
//! - [`ByteArrayIter`](crate::core::iter::ByteArrayIter) - Immutable iterator over bytes
//! - [`ByteArrayIterMut`](crate::core::iter::ByteArrayIterMut) - Mutable iterator over bytes
//!
//! ## Error Types
//! - [`ByteArrayError`](crate::errors::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) in insecure mode
//! - `AsRef<[u8]>` - Borrow as byte slice
//!
//! **Operations** (requires `ops_algebra` feature):
//! - `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 hardening tiers. When implementing features, use individual feature flags
//! (`sec_harden_zeroize`, `sec_harden_const_time_ops`, etc.) in `#[cfg]` attributes. Tiers (`sec_basic_hardening`,
//! `sec_enhanced_hardening`, `sec_maximum_hardening`) are convenience bundles for users to activate multiple features at once.
//!
//! **Security Hardening**: The `trust` module provides two mutually exclusive implementations:
//! - Hardened mode (any `sec_harden_*` feature): Restricts operations to prevent data leakage
//! - Insecure mode (default): Provides full `Vec<u8>` compatibility via Deref
//! See the Security Hardening Guide below for detailed information.
#![no_std]
#![forbid(unsafe_code)]

#[cfg(any(
    feature = "sec_harden_zeroize",
    feature = "sec_harden_const_time_ops",
    feature = "sec_harden_memlock",
    feature = "sec_harden_memencrypt"
))]
compile_error!(
    "The hardened feature is not yet implemented please deactivate and wait for a future release"
);
#[cfg(feature = "ops_simd")]
compile_error!("Currently not implemented");

extern crate alloc;

pub mod core {

    pub(crate) mod common;
    pub mod errors;
    pub mod model;

    pub mod iter;
    pub mod macros;
    #[cfg(feature = "ops_algebra")]
    pub mod ops;
    pub mod type_conv;

    pub mod trust {
        #[cfg(any(
            feature = "sec_harden_zeroize",
            feature = "sec_harden_memlock",
            feature = "sec_harden_const_time_ops",
            feature = "sec_harden_memencrypt"
        ))]
        pub mod hardened;

        #[cfg(not(any(
            feature = "sec_harden_zeroize",
            feature = "sec_harden_memlock",
            feature = "sec_harden_const_time_ops",
            feature = "sec_harden_memencrypt"
        )))]
        pub mod insecure;
    }
}

#[doc = include_str!("../docs/hardening.md")]
pub mod security_guide {}

pub use core::errors;
pub use core::macros;
pub use core::model::ByteArray;