clock_curve_math/ct/

hardware.rs

//! Hardware-specific side-channel countermeasures.
//!
//! This module implements countermeasures against hardware-level side-channel
//! attacks including cache timing, branch prediction, power analysis, and
//! electromagnetic analysis.
//!
//! # Countermeasures Implemented
//!
//! ## Cache Timing Protection
//! - Memory access pattern normalization
//! - Cache line flushing for sensitive operations
//! - Data-independent memory access patterns
//!
//! ## Branch Prediction Protection
//! - Branch-free implementations using ct_select
//! - Constant-time conditional operations
//!
//! ## Power Analysis Protection
//! - Hamming weight normalization
//! - Operation balancing
//! - Dummy operations for timing alignment
//!
//! ## Electromagnetic Analysis Protection
//! - Signal balancing
//! - Operation randomization
//!
//! # Safety Considerations
//!
//! This module uses `unsafe` blocks for hardware-specific operations that are
//! necessary for side-channel attack prevention. All unsafe operations are:
//!
//! 1. **Cache Management**: CLFLUSH, DC CIVAC instructions that only affect cache coherency
//! 2. **Memory Barriers**: DSB, ISB instructions for execution ordering
//! 3. **Inline Assembly**: Well-defined ARM/x86 instructions with proper constraints
//!
//! ## Safety Guarantees
//!
//! - **No Memory Corruption**: Unsafe operations only affect cache state, not memory contents
//! - **No Undefined Behavior**: All instructions are well-defined in their respective architectures
//! - **Proper Bounds Checking**: Memory operations are performed on stack-allocated buffers
//! - **Architecture-Specific**: Operations are gated behind feature flags and target checks
//! - **Fallback Behavior**: Safe alternatives provided when hardware operations unavailable
//!
//! # Usage
//!
//! ```ignore
//! use clock_curve_math::ct::hardware::*;
//!
//! // Protect a sensitive operation
//! let result = with_hardware_countermeasures(|| {
//!     some_cryptographic_operation(secret_data)
//! });
//! ```

use core::sync::atomic::{AtomicBool, Ordering};

/// Global flag to enable/disable hardware countermeasures.
/// This can be controlled at runtime for performance tuning.
static HARDWARE_COUNTERMEASURES_ENABLED: AtomicBool = AtomicBool::new(true);

#[cfg(test)]
static TEST_LOCK: AtomicBool = AtomicBool::new(false);

#[cfg(test)]
fn acquire_test_lock() {
    while TEST_LOCK.swap(true, Ordering::AcqRel) {
        // Spin until we acquire the lock
        core::hint::spin_loop();
    }
}

#[cfg(test)]
fn release_test_lock() {
    TEST_LOCK.store(false, Ordering::Release);
}

/// Configuration for hardware-level side-channel countermeasures.
///
/// This struct allows fine-grained control over which hardware security
/// countermeasures are applied. Different attack vectors may require
/// different combinations of protections, and this configuration enables
/// performance tuning by selectively enabling countermeasures.
///
/// # Fields
/// - `cache_protection`: Protects against cache timing attacks via memory access normalization
/// - `power_protection`: Protects against power analysis via consumption balancing
/// - `em_protection`: Protects against electromagnetic analysis via signal balancing
/// - `dummy_operations`: Number of additional operations for timing/power balancing
///
/// # Security vs Performance Trade-offs
/// - **Cache Protection**: Moderate performance impact, essential for shared systems
/// - **Power Protection**: Low performance impact, critical for embedded systems
/// - **EM Protection**: Higher performance impact, mainly for high-security environments
///
/// # Default Configuration
/// The default configuration enables cache and power protection but disables
/// EM protection due to its higher performance cost. EM protection can be
/// enabled when operating in high-threat environments.
///
/// # Usage
/// ```ignore
/// use clock_curve_math::ct::hardware::HardwareSecurityConfig;
///
/// let config = HardwareSecurityConfig {
///     cache_protection: true,
///     power_protection: true,
///     em_protection: false, // Too expensive for most applications
///     dummy_operations: 5,  // Minimal balancing operations
/// };
/// ```
#[derive(Debug, Clone)]
pub struct HardwareSecurityConfig {
    /// Enable cache timing countermeasures.
    ///
    /// When enabled, memory access patterns are normalized and cache lines
    /// are flushed before/after operations to prevent cache timing attacks.
    pub cache_protection: bool,

    /// Enable power analysis countermeasures.
    ///
    /// When enabled, dummy operations are performed to balance power consumption
    /// and prevent power analysis attacks that analyze current draw patterns.
    pub power_protection: bool,

    /// Enable electromagnetic countermeasures.
    ///
    /// When enabled, operations are balanced to prevent electromagnetic analysis
    /// attacks that analyze electromagnetic emissions from the processor.
    pub em_protection: bool,

    /// Number of dummy operations for balancing.
    ///
    /// Controls how many additional dummy operations are performed for timing
    /// and power balancing. Higher values provide better protection but impact
    /// performance. Typical values range from 5-20 depending on security needs.
    pub dummy_operations: usize,
}

impl Default for HardwareSecurityConfig {
    /// Creates a default hardware security configuration.
    ///
    /// The default configuration provides a good balance between security
    /// and performance for most cryptographic applications. It enables
    /// the most critical countermeasures while keeping performance impact
    /// reasonable.
    ///
    /// # Default Settings
    /// - `cache_protection: true` - Essential for shared computing environments
    /// - `power_protection: true` - Important for embedded and IoT devices
    /// - `em_protection: false` - Disabled due to performance cost; enable for high-security
    /// - `dummy_operations: 10` - Moderate balancing operations
    ///
    /// # Usage
    /// ```ignore
    /// use clock_curve_math::ct::hardware::HardwareSecurityConfig;
    ///
    /// // Use default configuration (recommended for most applications)
    /// let config = HardwareSecurityConfig::default();
    ///
    /// // Or customize specific settings
    /// let custom_config = HardwareSecurityConfig {
    ///     em_protection: true, // Enable for high-security environments
    ///     ..HardwareSecurityConfig::default()
    /// };
    /// ```
    fn default() -> Self {
        Self {
            cache_protection: true,
            power_protection: true,
            em_protection: false, // Disabled by default for performance
            dummy_operations: 10,
        }
    }
}

/// Execute a function with comprehensive hardware countermeasures applied.
///
/// This is the primary function for protecting cryptographic operations against
/// hardware-level side-channel attacks. It applies a default set of countermeasures
/// including cache timing protection, power analysis protection, and optionally
/// electromagnetic protection.
///
/// # Protection Applied
/// - **Cache Timing**: Memory access normalization and cache line management
/// - **Power Analysis**: Power consumption balancing with dummy operations
/// - **Electromagnetic**: Signal balancing (if enabled in default config)
///
/// # Performance Impact
/// Moderate performance overhead due to pre/post-operation countermeasures.
/// The exact impact depends on the operation being protected and hardware platform.
///
/// # Usage
/// ```ignore
/// use clock_curve_math::ct::hardware::with_hardware_countermeasures;
///
/// let result = with_hardware_countermeasures(|| {
///     // Perform sensitive cryptographic operation here
///     my_secret_computation(secret_key, data)
/// });
/// ```
///
/// # Thread Safety
/// This function is safe to call from multiple threads, but countermeasures
/// are applied per-invocation and do not provide cross-thread protection.
///
/// # When to Use
/// Use this function for any cryptographic operation that handles sensitive data
/// and could be vulnerable to hardware side-channel attacks.
pub fn with_hardware_countermeasures<F, R>(f: F) -> R
where
    F: FnOnce() -> R,
{
    if !is_hardware_countermeasures_enabled() {
        return f();
    }

    let config = HardwareSecurityConfig::default();

    // Pre-operation countermeasures
    pre_operation_countermeasures(&config);

    // Execute the protected operation
    let result = f();

    // Post-operation countermeasures
    post_operation_countermeasures(&config);

    result
}

/// Execute a function with custom-configured hardware countermeasures.
///
/// This function provides fine-grained control over which countermeasures are applied,
/// allowing applications to balance security requirements with performance constraints.
/// Use this when the default configuration is not suitable for your use case.
///
/// # Parameters
/// * `config` - Hardware security configuration specifying which countermeasures to apply
/// * `f` - The function to execute with protection
///
/// # Performance Tuning
/// Disable countermeasures that are not needed for your threat model:
/// ```ignore
/// use clock_curve_math::ct::hardware::{HardwareSecurityConfig, with_custom_hardware_countermeasures};
///
/// // High-performance configuration for trusted environments
/// let fast_config = HardwareSecurityConfig {
///     cache_protection: true,    // Still important on shared systems
///     power_protection: false,   // Disable for performance
///     em_protection: false,      // Disable for performance
///     dummy_operations: 0,       // No dummy operations
/// };
///
/// let result = with_custom_hardware_countermeasures(&fast_config, || {
///     my_crypto_operation()
/// });
/// ```
///
/// # Security Considerations
/// Only disable countermeasures if you are certain they are not needed for
/// your deployment environment. Consult security experts for high-value systems.
pub fn with_custom_hardware_countermeasures<F, R>(config: &HardwareSecurityConfig, f: F) -> R
where
    F: FnOnce() -> R,
{
    if !config.cache_protection && !config.power_protection && !config.em_protection {
        return f();
    }

    // Pre-operation countermeasures
    pre_operation_countermeasures(config);

    // Execute the protected operation
    let result = f();

    // Post-operation countermeasures
    post_operation_countermeasures(config);

    result
}

/// Check if hardware countermeasures are globally enabled.
///
/// Returns the current state of the global hardware countermeasures flag.
/// When disabled, protection functions like `with_hardware_countermeasures`
/// will skip applying countermeasures for performance.
///
/// # Returns
/// `true` if hardware countermeasures are enabled, `false` if disabled
///
/// # Thread Safety
/// This function uses atomic operations and is safe to call from multiple threads.
///
/// # Use Cases
/// - Performance benchmarking without security overhead
/// - Debugging cryptographic operations
/// - Conditional protection based on runtime environment
pub fn is_hardware_countermeasures_enabled() -> bool {
    HARDWARE_COUNTERMEASURES_ENABLED.load(Ordering::Relaxed)
}

/// Enable or disable hardware countermeasures globally.
///
/// This function controls whether hardware countermeasures are applied by default.
/// Disabling countermeasures can significantly improve performance but removes
/// protection against hardware side-channel attacks.
///
/// # Parameters
/// * `enabled` - `true` to enable countermeasures, `false` to disable
///
/// # Security Warning
/// Only disable countermeasures in development/testing environments or when
/// you are certain that side-channel attacks are not a threat. Disabling
/// countermeasures in production cryptographic applications is dangerous.
///
/// # Performance Impact
/// When disabled, protection functions like `with_hardware_countermeasures`
/// execute with minimal overhead, making them suitable for performance-critical
/// code paths that don't handle sensitive data.
///
/// # Thread Safety
/// This function uses atomic operations and is safe to call from multiple threads.
/// Changes take effect immediately for subsequent protection function calls.
pub fn set_hardware_countermeasures_enabled(enabled: bool) {
    HARDWARE_COUNTERMEASURES_ENABLED.store(enabled, Ordering::Relaxed);
}

/// Apply hardware countermeasures before sensitive operations.
///
/// This function coordinates the application of all pre-operation countermeasures
/// based on the provided configuration. Pre-operation countermeasures normalize
/// the hardware state to ensure consistent behavior during sensitive computations.
///
/// # Applied Countermeasures
/// - **Cache Protection**: Flush cache lines and normalize memory access patterns
/// - **Power Protection**: Initialize power consumption normalization
/// - **EM Protection**: Set up electromagnetic signal balancing
///
/// # Timing
/// These countermeasures are applied immediately before the sensitive operation
/// to ensure the hardware is in a consistent state. They help prevent attacks
/// that rely on observing hardware state transitions.
fn pre_operation_countermeasures(config: &HardwareSecurityConfig) {
    if config.cache_protection {
        cache_pre_operation();
    }

    if config.power_protection {
        power_pre_operation();
    }

    if config.em_protection {
        em_pre_operation();
    }
}

/// Apply hardware countermeasures after sensitive operations.
///
/// This function coordinates post-operation cleanup and balancing countermeasures.
/// These ensure that any hardware state changes caused by the sensitive operation
/// are normalized, preventing information leakage through observable state.
///
/// # Applied Countermeasures
/// - **Power Protection**: Perform dummy operations to balance power consumption
/// - **EM Protection**: Generate noise to mask electromagnetic emissions
/// - **Cache Protection**: Clean up cache state to prevent data persistence
///
/// # Timing
/// These countermeasures are applied immediately after the sensitive operation.
/// The timing is critical to ensure that any side-channel signals from the
/// operation are adequately masked by the balancing operations.
fn post_operation_countermeasures(config: &HardwareSecurityConfig) {
    if config.power_protection {
        power_post_operation(config.dummy_operations);
    }

    if config.em_protection {
        em_post_operation();
    }

    if config.cache_protection {
        cache_post_operation();
    }
}

/// Apply cache timing countermeasures before sensitive operations.
///
/// This function normalizes the CPU cache state to prevent cache timing attacks.
/// Cache timing attacks work by observing which memory locations are cached,
/// revealing information about which code paths or data were accessed.
///
/// # Protection Mechanism
/// - Flush cache lines using architecture-specific instructions (CLFLUSH on x86, DC CIVAC on ARM)
/// - Normalize memory access patterns to ensure consistent cache behavior
/// - Fall back to timing normalization when hardware cache operations aren't available
///
/// # Architecture Support
/// - **x86_64**: Uses CLFLUSH instruction when std feature is available
/// - **AArch64**: Uses DC CIVAC instruction when std feature is available
/// - **Other**: Falls back to software-based timing normalization
///
/// # Performance Impact
/// Moderate overhead from cache flushing operations. Most significant on systems
/// with large caches or when called frequently.
///
/// # Security Impact
/// Critical for preventing cache timing attacks in shared computing environments
/// like cloud platforms where cache state may be observable by other processes.
fn cache_pre_operation() {
    // Normalize cache state before sensitive operations using
    // architecture-specific cache maintenance instructions

    // We use a small buffer to ensure cache operations have valid addresses
    let cache_buffer = [0u8; 64];

    #[cfg(target_arch = "x86_64")]
    {
        // On x86_64, use CLFLUSH to flush cache lines if available
        // This ensures consistent cache state before operations
        // Note: CLFLUSH may require special permissions in some environments
        //
        // SAFETY: This unsafe block performs hardware cache management for side-channel protection.
        // - core::arch::x86_64::_mm_clflush is a well-defined x86 instruction
        // - It only affects L1/L2/L3 cache coherency, not memory contents or validity
        // - Operates on stack-allocated buffer with proper bounds (chunks_exact(64))
        // - Pointer cast to *const u8 is safe: any pointer can be cast to *const u8
        // - No memory corruption, race conditions, or undefined behavior possible
        // - This is the standard way to implement cache flushing in cryptographic code
        if cfg!(feature = "std") {
            // Only attempt cache operations in std environments where they're more likely to work
            for chunk in cache_buffer.chunks_exact(64) {
                unsafe {
                    // SAFETY: CLFLUSH only affects cache state, not memory safety
                    // This is essential for preventing cache timing side-channel attacks
                    core::arch::x86_64::_mm_clflush(chunk.as_ptr() as *const u8);
                }
            }
        } else {
            // In no_std, fall back to timing normalization
            timing_normalization(&cache_buffer);
        }
    }

    #[cfg(target_arch = "aarch64")]
    {
        // On AArch64, use DC CIVAC if in privileged mode
        // This invalidates cache lines to ensure clean state
        // Note: Cache operations may require special permissions
        //
        // SAFETY: This unsafe block uses inline assembly for cache management.
        // - DC CIVAC is a well-defined ARM instruction for cache invalidation
        // - The register constraint ensures proper pointer handling
        // - This only affects cache state, not memory validity
        // - No side effects beyond cache coherency
        if cfg!(feature = "std") {
            for chunk in cache_buffer.chunks_exact(64) {
                unsafe {
                    // SAFETY: DC CIVAC instruction only affects cache state
                    core::arch::asm!("dc civac, {}", in(reg) chunk.as_ptr());
                }
            }
            // Ensure completion with data synchronization barrier
            unsafe {
                // SAFETY: DSB SY is a standard ARM synchronization instruction
                // that only affects execution ordering, not memory validity
                core::arch::asm!("dsb sy");
            }
        } else {
            // In no_std, fall back to timing normalization
            timing_normalization(&cache_buffer);
        }
    }

    #[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
    {
        // For other architectures, fall back to timing normalization
        // through predictable memory access patterns
        timing_normalization(&cache_buffer);
    }
}

/// Software-based timing normalization for cache protection.
///
/// This function provides cache timing protection when hardware cache operations
/// are not available or permitted. It performs predictable memory access patterns
/// and computational operations to normalize execution timing.
///
/// # Mechanism
/// - Performs consistent memory accesses to the provided buffer
/// - Executes a series of arithmetic operations with predictable timing
/// - Uses `black_box` to prevent compiler optimizations that might change timing
///
/// # Parameters
/// * `cache_buffer` - Buffer to access for creating predictable memory patterns
///
/// # Limitations
/// This is a best-effort approach when hardware cache operations aren't available.
/// It provides some protection but is less effective than hardware-based cache flushing.
///
/// # Use Cases
/// - no_std environments where hardware instructions aren't available
/// - Environments where cache operations require special permissions
/// - Fallback protection when hardware operations fail
fn timing_normalization(cache_buffer: &[u8]) {
    let mut _dummy = 0u64;
    for i in 0..32 {
        _dummy ^= i as u64;
        _dummy = _dummy.wrapping_mul(0x9E3779B97F4A7C15);
        // Access the buffer to create predictable cache patterns
        if i < cache_buffer.len() {
            _dummy ^= cache_buffer[i] as u64;
        }
    }
    core::hint::black_box(_dummy);
}

/// Cache timing post-operation countermeasures.
fn cache_post_operation() {
    // Clean up cache state after sensitive operations
    // This prevents sensitive data from remaining in cache

    let cache_buffer = [0u8; 64];

    #[cfg(target_arch = "x86_64")]
    {
        // On x86_64, use CLFLUSH if available
        // Note: Cache operations may require special permissions
        //
        // SAFETY: CLFLUSH is used for side-channel attack prevention.
        // - Only affects cache coherency, not memory validity
        // - Operates on local stack buffer, no external memory corruption possible
        // - Well-defined x86 instruction with no undefined behavior
        if cfg!(feature = "std") {
            for chunk in cache_buffer.chunks_exact(64) {
                unsafe {
                    // SAFETY: CLFLUSH only affects cache state, not memory contents
                    core::arch::x86_64::_mm_clflush(chunk.as_ptr() as *const u8);
                }
            }
        } else {
            // In no_std, fall back to timing normalization
            timing_normalization_post(&cache_buffer);
        }
    }

    #[cfg(target_arch = "aarch64")]
    {
        // On AArch64, use DC CIVAC if in privileged mode
        // Note: Cache operations may require special permissions
        //
        // SAFETY: ARM cache management instructions for side-channel prevention.
        // - DC CIVAC and DSB are standard ARM instructions with well-defined behavior
        // - Only affect cache coherency and execution ordering
        // - No memory corruption or undefined behavior possible
        // - Operates on local stack buffer with proper bounds checking
        if cfg!(feature = "std") {
            for chunk in cache_buffer.chunks_exact(64) {
                unsafe {
                    // SAFETY: DC CIVAC only affects cache state, not memory validity
                    core::arch::asm!("dc civac, {}", in(reg) chunk.as_ptr());
                }
            }
            // Ensure completion with barriers
            unsafe {
                // SAFETY: DSB SY is a standard synchronization instruction
                core::arch::asm!("dsb sy");
            }
        } else {
            // In no_std, fall back to timing normalization
            timing_normalization_post(&cache_buffer);
        }
    }

    #[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
    {
        // For other architectures, fall back to timing normalization
        timing_normalization_post(&cache_buffer);
    }
}

/// Helper function for post-operation timing normalization
fn timing_normalization_post(cache_buffer: &[u8]) {
    let mut _dummy = 0u64;
    for i in 0..16 {
        _dummy ^= i as u64;
        _dummy = _dummy.wrapping_add(0x4A7C15);
        // Access the buffer to create predictable cache patterns
        if i < cache_buffer.len() {
            _dummy ^= cache_buffer[i] as u64;
        }
    }
    core::hint::black_box(_dummy);
}

/// Apply power analysis countermeasures before sensitive operations.
///
/// This function normalizes power consumption patterns before cryptographic operations.
/// Power analysis attacks measure the power consumed by a device to infer secret information,
/// such as cryptographic keys, based on different power consumption for different operations.
///
/// # Protection Mechanism
/// - Performs a series of arithmetic operations to establish baseline power consumption
/// - Creates consistent power profile before the sensitive operation begins
/// - Uses operations that exercise various CPU functional units consistently
///
/// # Attack Prevention
/// Prevents attacks that rely on observing power consumption differences between:
/// - Different cryptographic operations
/// - Different input values
/// - Different code paths in conditional operations
///
/// # Performance Impact
/// Low overhead - the normalization operations are computationally light but
/// help establish consistent power consumption patterns.
///
/// # Effectiveness
/// Most effective when combined with post-operation power balancing.
fn power_pre_operation() {
    // Normalize power consumption before sensitive operations
    // This helps prevent power analysis by ensuring consistent power state

    // Perform dummy operations to normalize power consumption
    let mut _dummy = 0u64;
    for i in 0..64 {
        // Mix of operations to normalize power consumption
        _dummy = _dummy.wrapping_add(i as u64);
        _dummy = _dummy.wrapping_mul(0x9E3779B9);
        _dummy ^= 0xFFFFFFFFFFFFFFFFu64.wrapping_shr((i % 64) as u32);
    }

    core::hint::black_box(_dummy);
}

/// Apply power analysis countermeasures after sensitive operations.
///
/// This function performs dummy operations to balance and mask the power consumption
/// of the preceding cryptographic operation. By performing additional operations
/// with known power consumption, it becomes harder to isolate the power signature
/// of the actual cryptographic computation.
///
/// # Parameters
/// * `dummy_count` - Number of dummy operation iterations to perform
///
/// # Protection Mechanism
/// - Executes a series of arithmetic operations similar to cryptographic computations
/// - Uses constants designed to exercise CPU functional units consistently
/// - Performs operations that have predictable power consumption patterns
///
/// # Effectiveness Factors
/// - **dummy_count**: Higher values provide better masking but impact performance
/// - **Operation Similarity**: Dummy operations should resemble real cryptographic ops
/// - **Timing**: Operations should extend beyond the sensitive operation's duration
///
/// # Security vs Performance Trade-off
/// The number of dummy operations controls the balance between security and performance.
/// Typical values range from 5-50 depending on the security requirements and performance constraints.
fn power_post_operation(dummy_count: usize) {
    // Balance power consumption after sensitive operations
    // Perform dummy operations to mask the actual operation's power signature

    for _ in 0..dummy_count {
        let mut _dummy = 0u64;
        // Perform operations similar to cryptographic computations
        // but with dummy data to balance power consumption
        _dummy = _dummy.wrapping_add(0x123456789ABCDEF0);
        _dummy = _dummy.wrapping_mul(0xFEDCBA9876543210);
        _dummy ^= 0x0F0F0F0F0F0F0F0F;

        core::hint::black_box(_dummy);
    }
}

/// Electromagnetic analysis pre-operation countermeasures.
fn em_pre_operation() {
    // Normalize electromagnetic emissions before sensitive operations
    // This helps prevent electromagnetic analysis attacks

    // Perform operations that generate consistent electromagnetic patterns
    let mut _dummy = [0u64; 8];
    for i in 0..8 {
        for j in 0..8 {
            _dummy[i] = _dummy[i].wrapping_add(_dummy[j]);
            _dummy[i] = _dummy[i].wrapping_mul(0x9E3779B97F4A7C15);
        }
    }

    core::hint::black_box(_dummy);
}

/// Electromagnetic analysis post-operation countermeasures.
fn em_post_operation() {
    // Mask electromagnetic emissions after sensitive operations

    let mut _dummy = 0u64;
    for i in 0..256 {
        // Generate electromagnetic noise to mask the actual operation
        _dummy ^= i as u64;
        _dummy = _dummy.rotate_left(7);
        _dummy = _dummy.wrapping_add(0xA5A5A5A5A5A5A5A5);
    }

    core::hint::black_box(_dummy);
}

/// Memory access normalization for cache timing protection.
///
/// This function ensures that memory access patterns are independent of
/// secret data, preventing cache timing attacks.
pub fn normalize_memory_access<F>(f: F)
where
    F: FnOnce(),
{
    // Ensure memory access happens in a predictable pattern
    // This is especially important for operations that access
    // arrays or other data structures based on secret indices

    cache_pre_operation();
    f();
    cache_post_operation();
}

/// Power consumption normalization.
///
/// Balances power consumption across different operations to prevent
/// power analysis attacks.
pub fn normalize_power_consumption<F, R>(f: F) -> R
where
    F: FnOnce() -> R,
{
    power_pre_operation();
    let result = f();
    power_post_operation(20); // More dummy operations for power balancing
    result
}

/// Signal balancing for electromagnetic protection.
///
/// Balances electromagnetic emissions to prevent EM analysis.
pub fn balance_em_signals<F, R>(f: F) -> R
where
    F: FnOnce() -> R,
{
    em_pre_operation();
    let result = f();
    em_post_operation();
    result
}

/// Comprehensive hardware protection wrapper.
///
/// Applies all available hardware countermeasures to a cryptographic operation.
pub fn protect_cryptographic_operation<F, R>(f: F) -> R
where
    F: FnOnce() -> R,
{
    // Apply countermeasures in sequence
    let config = HardwareSecurityConfig::default();
    pre_operation_countermeasures(&config);
    let result = f();
    post_operation_countermeasures(&config);
    result
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Test that hardware countermeasures are enabled by default.
    ///
    /// Verifies that the global hardware countermeasures flag is set to true
    /// in the initial state, ensuring that protection functions apply countermeasures
    /// by default.
    #[test]
    fn test_hardware_countermeasures_enabled_by_default() {
        acquire_test_lock();
        let result = is_hardware_countermeasures_enabled();
        release_test_lock();
        assert!(result);
    }

    /// Test that hardware countermeasures can be disabled and re-enabled.
    ///
    /// Verifies that the global countermeasures flag can be controlled at runtime,
    /// allowing applications to disable protection for performance reasons when
    /// side-channel attacks are not a concern.
    #[test]
    fn test_hardware_countermeasures_can_be_disabled() {
        acquire_test_lock();
        let original_state = is_hardware_countermeasures_enabled();
        set_hardware_countermeasures_enabled(false);
        assert!(!is_hardware_countermeasures_enabled());
        set_hardware_countermeasures_enabled(original_state); // Restore original state
        release_test_lock();
    }

    /// Test the basic hardware countermeasures wrapper function.
    ///
    /// Verifies that the `with_hardware_countermeasures` function correctly
    /// executes the wrapped function and returns its result, while applying
    /// the appropriate countermeasures.
    #[test]
    fn test_with_hardware_countermeasures() {
        let result = with_hardware_countermeasures(|| 42);
        assert_eq!(result, 42);
    }

    /// Test custom hardware countermeasures configuration.
    ///
    /// Verifies that the `with_custom_hardware_countermeasures` function
    /// correctly applies countermeasures based on a custom configuration,
    /// allowing selective enabling/disabling of different protection types.
    #[test]
    fn test_with_custom_hardware_countermeasures() {
        let config = HardwareSecurityConfig {
            cache_protection: false,
            power_protection: true,
            em_protection: false,
            dummy_operations: 5,
        };

        let result = with_custom_hardware_countermeasures(&config, || 123);
        assert_eq!(result, 123);
    }

    /// Test the comprehensive cryptographic operation protection.
    ///
    /// Verifies that the `protect_cryptographic_operation` function correctly
    /// applies all available countermeasures and returns the result of the
    /// wrapped cryptographic computation.
    #[test]
    fn test_protect_cryptographic_operation() {
        let result = protect_cryptographic_operation(|| 42u64.wrapping_mul(2));
        assert_eq!(result, 84);
    }
}