adaptive_pipeline_domain/services/

encryption_service.rs

// /////////////////////////////////////////////////////////////////////////////
// Adaptive Pipeline
// Copyright (c) 2025 Michael Gardner, A Bit of Help, Inc.
// SPDX-License-Identifier: BSD-3-Clause
// See LICENSE file in the project root.
// /////////////////////////////////////////////////////////////////////////////

//! # Encryption Service
//!
//! Domain service trait for authenticated encryption (AEAD) with algorithms
//! (AES-256-GCM, ChaCha20-Poly1305), secure key derivation (Argon2, Scrypt,
//! PBKDF2), and memory zeroization. Provides chunk-by-chunk streaming,
//! tampering detection, and security context integration. Thread-safe,
//! stateless operations. See mdBook for algorithm comparison and security
//! features.
//! concurrently across multiple threads. The service maintains no mutable state
//! and all operations are stateless.
//!
//! ## Integration
//!
//! The encryption service integrates with:
//!
//! - **Security Context**: Access control and security policies
//! - **Pipeline Processing**: Core pipeline stage processing
//! - **Key Management**: Secure key storage and retrieval
//! - **Audit Logging**: Security event tracking and compliance

use serde::{Deserialize, Serialize};

use crate::services::datetime_serde;
use crate::value_objects::EncryptionBenchmark;
use crate::{FileChunk, PipelineError, ProcessingContext, SecurityContext};
use zeroize::{Zeroize, ZeroizeOnDrop};

// NOTE: Domain traits are synchronous. Async execution is an infrastructure
// concern. Infrastructure can provide async adapters that wrap sync
// implementations.

/// Encryption algorithms supported by the adaptive pipeline system
///
/// This enum provides type-safe selection of encryption algorithms with
/// different performance characteristics and security properties. All
/// algorithms provide authenticated encryption with associated data (AEAD) for
/// both confidentiality and integrity protection.
///
/// # Algorithm Characteristics
///
/// - **AES-256-GCM**: Industry standard with 256-bit keys, excellent
///   performance
/// - **ChaCha20-Poly1305**: Modern stream cipher, constant-time implementation
/// - **AES-128-GCM**: Faster variant with 128-bit keys, still highly secure
/// - **AES-192-GCM**: Middle ground with 192-bit keys
/// - **Custom**: User-defined algorithms for specialized requirements
///
/// # Security Properties
///
/// All algorithms provide:
/// - **Confidentiality**: Data is encrypted and unreadable without the key
/// - **Integrity**: Tampering is detected through authentication tags
/// - **Authentication**: Verifies data origin and prevents forgery
/// - **Semantic Security**: Identical plaintexts produce different ciphertexts
///
/// # Examples
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum EncryptionAlgorithm {
    Aes256Gcm,
    ChaCha20Poly1305,
    Aes128Gcm,
    Aes192Gcm,
    Custom(String),
}

/// Key derivation functions for secure key generation from passwords or key
/// material
///
/// This enum provides type-safe selection of key derivation functions (KDFs)
/// with different security properties and performance characteristics. All
/// functions are designed to be computationally expensive to resist brute-force
/// attacks.
///
/// # Function Characteristics
///
/// - **Argon2**: Memory-hard function, winner of Password Hashing Competition
/// - **Scrypt**: Memory-hard function with tunable parameters
/// - **PBKDF2**: Standard function with configurable iterations
/// - **Custom**: User-defined functions for specialized requirements
///
/// # Security Properties
///
/// - **Argon2**: Resistant to GPU and ASIC attacks, configurable memory and
///   time costs
/// - **Scrypt**: Good resistance to hardware attacks, balanced memory/time
///   trade-offs
/// - **PBKDF2**: Widely supported, but more vulnerable to specialized hardware
///   attacks
///
/// # Performance Considerations
///
/// | Function | Speed | Memory Usage | GPU Resistance | ASIC Resistance |
/// |----------|-------|--------------|----------------|------------------|
/// | Argon2   | Slow  | High         | Excellent      | Excellent        |
/// | Scrypt   | Medium| Medium       | Good           | Good             |
/// | PBKDF2   | Fast  | Low          | Poor           | Poor             |
///
/// # Examples
#[derive(Debug, Clone, PartialEq)]
pub enum KeyDerivationFunction {
    /// Argon2 - Memory-hard function resistant to GPU and ASIC attacks
    /// Winner of the Password Hashing Competition, provides excellent security
    Argon2,

    /// Scrypt - Memory-hard function with tunable parameters
    /// Good balance of security and performance
    Scrypt,

    /// PBKDF2 - Standard key derivation function
    /// Widely supported but less resistant to specialized attacks
    Pbkdf2,

    /// Custom key derivation function for specialized requirements
    Custom(String),
}

/// Encryption configuration that encapsulates all parameters for encryption
/// operations
///
/// This configuration struct provides comprehensive control over encryption
/// behavior, including algorithm selection, key derivation parameters, and
/// security settings. The configuration is immutable and thread-safe.
///
/// # Configuration Parameters
///
/// - **Algorithm**: The encryption algorithm to use
/// - **Key Derivation**: Function for deriving keys from passwords
/// - **Key Size**: Size of encryption keys in bytes
/// - **Nonce Size**: Size of nonces/initialization vectors in bytes
/// - **Salt Size**: Size of salt for key derivation in bytes
/// - **Iterations**: Number of iterations for key derivation
/// - **Memory Cost**: Memory usage for memory-hard functions (optional)
/// - **Parallel Cost**: Parallelism level for key derivation (optional)
/// - **Associated Data**: Additional authenticated data (optional)
///
/// # Examples
///
///
/// # Security Considerations
///
/// - **Key Size**: Larger keys provide better security but may impact
///   performance
/// - **Iterations**: Higher iteration counts increase security but slow key
///   derivation
/// - **Memory Cost**: Higher memory usage improves resistance to attacks
/// - **Salt Size**: Larger salts prevent rainbow table attacks
/// - **Associated Data**: Additional data authenticated but not encrypted
#[derive(Debug, Clone)]
pub struct EncryptionConfig {
    /// The encryption algorithm to use for processing
    pub algorithm: EncryptionAlgorithm,

    /// Key derivation function for generating keys from passwords
    pub key_derivation: KeyDerivationFunction,

    /// Size of encryption keys in bytes
    pub key_size: u32,

    /// Size of nonces/initialization vectors in bytes
    pub nonce_size: u32,

    /// Size of salt for key derivation in bytes
    pub salt_size: u32,

    /// Number of iterations for key derivation functions
    pub iterations: u32,

    /// Memory cost for memory-hard functions (bytes)
    pub memory_cost: Option<u32>,

    /// Parallelism level for key derivation functions
    pub parallel_cost: Option<u32>,

    /// Additional authenticated data (not encrypted)
    pub associated_data: Option<Vec<u8>>,
}

/// Key material for encryption/decryption operations with secure memory
/// management
///
/// This struct contains all cryptographic material needed for encryption and
/// decryption operations. It implements secure memory management through the
/// `Zeroize` trait to ensure sensitive data is properly cleared from memory
/// when no longer needed.
///
/// # Security Features
///
/// - **Automatic Zeroization**: Keys are securely wiped from memory on drop
/// - **Expiration Support**: Keys can have expiration times for security
///   policies
/// - **Algorithm Binding**: Keys are bound to specific algorithms
/// - **Timestamp Tracking**: Creation time tracking for audit and compliance
///
/// # Key Material Components
///
/// - **Key**: The actual encryption/decryption key
/// - **Nonce**: Unique number used once per encryption operation
/// - **Salt**: Random data used in key derivation
/// - **Algorithm**: The encryption algorithm this key is for
/// - **Created At**: When the key material was generated
/// - **Expires At**: Optional expiration time for key rotation
///
/// # Examples
///
///
/// # Memory Security
///
/// The key material implements `Zeroize` to ensure sensitive data is securely
/// cleared from memory:
///
///
/// # Serialization
///
/// Key material can be serialized for storage, but care must be taken to:
/// - Encrypt serialized key material
/// - Use secure storage mechanisms
/// - Implement proper access controls
/// - Follow key management best practices
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct KeyMaterial {
    /// The encryption/decryption key (sensitive data)
    pub key: Vec<u8>,

    /// Nonce/initialization vector for encryption operations
    pub nonce: Vec<u8>,

    /// Salt used in key derivation (if applicable)
    pub salt: Vec<u8>,

    /// The encryption algorithm this key material is for
    pub algorithm: EncryptionAlgorithm,

    /// When this key material was created (RFC3339 format)
    #[serde(with = "datetime_serde")]
    pub created_at: chrono::DateTime<chrono::Utc>,

    /// Optional expiration time for key rotation (RFC3339 format)
    #[serde(with = "datetime_serde::optional")]
    pub expires_at: Option<chrono::DateTime<chrono::Utc>>,
}

impl Zeroize for KeyMaterial {
    fn zeroize(&mut self) {
        self.key.zeroize();
        self.nonce.zeroize();
        self.salt.zeroize();
    }
}

impl ZeroizeOnDrop for KeyMaterial {}

impl KeyMaterial {
    pub fn len(&self) -> usize {
        self.key.len()
    }

    pub fn is_empty(&self) -> bool {
        self.key.is_empty()
    }

    pub fn new(key: Vec<u8>, nonce: Vec<u8>, salt: Vec<u8>, algorithm: EncryptionAlgorithm) -> Self {
        Self {
            key,
            nonce,
            salt,
            algorithm,
            created_at: chrono::Utc::now(),
            expires_at: None,
        }
    }
}

/// Domain service interface for encryption operations
///
/// This trait is **synchronous** following DDD principles. The domain layer
/// defines *what* operations exist, not *how* they execute. Async execution
/// is an infrastructure concern. Infrastructure adapters can wrap this trait
/// to provide async interfaces when needed.
///
/// # Note on Async
///
/// For async contexts, use `AsyncEncryptionAdapter` from the infrastructure
/// layer.
///
/// # Note on Parallel Processing
///
/// Parallel processing of chunks (encrypt_chunks_parallel,
/// decrypt_chunks_parallel) is an infrastructure concern and has been removed
/// from the domain trait. Use infrastructure adapters for batch/parallel
/// operations.
///
/// # Unified Stage Interface
///
/// This trait extends `StageService`, providing the unified `process_chunk()`
/// method that all stages implement. The specialized `encrypt_chunk()` and
/// `decrypt_chunk()` methods are maintained for backward compatibility and
/// internal use, but `process_chunk()` is the primary interface used by the
/// pipeline system.
pub trait EncryptionService: super::stage_service::StageService {
    /// Encrypts a file chunk using the specified configuration and key material
    ///
    /// # Note on Async
    ///
    /// This method is synchronous in the domain. For async contexts,
    /// use `AsyncEncryptionAdapter` from the infrastructure layer.
    fn encrypt_chunk(
        &self,
        chunk: FileChunk,
        config: &EncryptionConfig,
        key_material: &KeyMaterial,
        context: &mut ProcessingContext,
    ) -> Result<FileChunk, PipelineError>;

    /// Decrypts a file chunk using the specified configuration and key material
    ///
    /// # Note on Async
    ///
    /// This method is synchronous in the domain. For async contexts,
    /// use `AsyncEncryptionAdapter` from the infrastructure layer.
    fn decrypt_chunk(
        &self,
        chunk: FileChunk,
        config: &EncryptionConfig,
        key_material: &KeyMaterial,
        context: &mut ProcessingContext,
    ) -> Result<FileChunk, PipelineError>;

    /// Derives key material from password using the specified KDF
    ///
    /// # Note
    ///
    /// This is a CPU-intensive operation. Use infrastructure adapters
    /// to execute in blocking thread pool when called from async contexts.
    fn derive_key_material(
        &self,
        password: &str,
        config: &EncryptionConfig,
        security_context: &SecurityContext,
    ) -> Result<KeyMaterial, PipelineError>;

    /// Generates random key material for encryption operations
    ///
    /// # Note
    ///
    /// This operation uses cryptographically secure random number generation.
    /// Execution is synchronous in domain, wrap with adapter for async
    /// contexts.
    fn generate_key_material(
        &self,
        config: &EncryptionConfig,
        security_context: &SecurityContext,
    ) -> Result<KeyMaterial, PipelineError>;

    /// Validates encryption configuration parameters
    ///
    /// Checks if the configuration is valid and supported by this
    /// implementation.
    fn validate_config(&self, config: &EncryptionConfig) -> Result<(), PipelineError>;

    /// Gets list of supported encryption algorithms
    ///
    /// Returns the algorithms that this implementation can handle.
    fn supported_algorithms(&self) -> Vec<EncryptionAlgorithm>;

    /// Benchmarks encryption performance with sample data
    ///
    /// # Note
    ///
    /// This is a CPU-intensive operation. Use infrastructure adapters
    /// for async execution in blocking thread pool.
    fn benchmark_algorithm(
        &self,
        algorithm: &EncryptionAlgorithm,
        test_data: &[u8],
    ) -> Result<EncryptionBenchmark, PipelineError>;

    /// Securely wipes key material from memory
    ///
    /// Ensures sensitive key data is properly zeroized before deallocation.
    fn wipe_key_material(&self, key_material: &mut KeyMaterial) -> Result<(), PipelineError>;

    /// Stores key material securely (e.g., HSM integration)
    ///
    /// # Note
    ///
    /// This may involve I/O operations. Infrastructure implementations
    /// should use appropriate async adapters when needed.
    fn store_key_material(
        &self,
        key_material: &KeyMaterial,
        key_id: &str,
        security_context: &SecurityContext,
    ) -> Result<(), PipelineError>;

    /// Retrieves key material securely (e.g., from HSM)
    ///
    /// # Note
    ///
    /// This may involve I/O operations. Infrastructure implementations
    /// should use appropriate async adapters when needed.
    fn retrieve_key_material(
        &self,
        key_id: &str,
        security_context: &SecurityContext,
    ) -> Result<KeyMaterial, PipelineError>;

    /// Rotates encryption keys to new configuration
    ///
    /// Returns the new key ID for the rotated keys.
    ///
    /// # Note
    ///
    /// This may involve I/O operations. Infrastructure implementations
    /// should use appropriate async adapters when needed.
    fn rotate_keys(
        &self,
        old_key_id: &str,
        new_config: &EncryptionConfig,
        security_context: &SecurityContext,
    ) -> Result<String, PipelineError>;
}

impl Default for EncryptionConfig {
    fn default() -> Self {
        Self {
            algorithm: EncryptionAlgorithm::Aes256Gcm,
            key_derivation: KeyDerivationFunction::Argon2,
            key_size: 32,   // 256 bits
            nonce_size: 12, // 96 bits for GCM
            salt_size: 16,  // 128 bits
            iterations: 100_000,
            memory_cost: Some(65536), // 64MB for Argon2
            parallel_cost: Some(1),
            associated_data: None,
        }
    }
}

impl EncryptionConfig {
    /// Creates a new encryption configuration
    pub fn new(algorithm: EncryptionAlgorithm) -> Self {
        Self {
            algorithm,
            ..Default::default()
        }
    }

    /// Sets key derivation function
    pub fn with_key_derivation(mut self, kdf: KeyDerivationFunction) -> Self {
        self.key_derivation = kdf;
        self
    }

    /// Sets key size
    pub fn with_key_size(mut self, size: u32) -> Self {
        self.key_size = size;
        self
    }

    /// Sets iterations
    pub fn with_iterations(mut self, iterations: u32) -> Self {
        self.iterations = iterations;
        self
    }

    /// Sets memory cost (for Argon2)
    pub fn with_memory_cost(mut self, cost: u32) -> Self {
        self.memory_cost = Some(cost);
        self
    }

    /// Sets parallel cost (for Argon2)
    pub fn with_parallel_cost(mut self, cost: u32) -> Self {
        self.parallel_cost = Some(cost);
        self
    }

    /// Sets associated data
    pub fn with_associated_data(mut self, data: Vec<u8>) -> Self {
        self.associated_data = Some(data);
        self
    }

    /// Creates a high-security configuration
    pub fn high_security() -> Self {
        Self {
            algorithm: EncryptionAlgorithm::Aes256Gcm,
            key_derivation: KeyDerivationFunction::Argon2,
            key_size: 32,
            nonce_size: 12,
            salt_size: 32,              // Larger salt
            iterations: 1_000_000,      // More iterations
            memory_cost: Some(1048576), // 1GB for Argon2
            parallel_cost: Some(4),
            associated_data: None,
        }
    }

    /// Creates a performance-optimized configuration
    pub fn performance_optimized() -> Self {
        Self {
            algorithm: EncryptionAlgorithm::ChaCha20Poly1305,
            key_derivation: KeyDerivationFunction::Argon2,
            key_size: 32,
            nonce_size: 12,
            salt_size: 16,
            iterations: 10_000,      // Fewer iterations
            memory_cost: Some(8192), // 8MB for Argon2
            parallel_cost: Some(1),
            associated_data: None,
        }
    }
}

/// Implementation of `FromParameters` for type-safe config extraction.
///
/// This implementation converts `StageConfiguration.parameters` HashMap
/// into a typed `EncryptionConfig` object.
///
/// ## Expected Parameters
///
/// - **algorithm** (required): Encryption algorithm name
///   - Valid values: "aes256gcm", "aes128gcm", "chacha20poly1305",
///     "xchacha20poly1305"
///   - Example: `"algorithm" => "aes256gcm"`
///
/// - **key_size** (optional): Key size in bytes
///   - Default: 32
///   - Example: `"key_size" => "32"`
///
/// - **iterations** (optional): KDF iterations
///   - Default: 3
///   - Example: `"iterations" => "10000"`
///
/// ## Usage Example
///
/// ```rust
/// use adaptive_pipeline_domain::services::{EncryptionConfig, FromParameters};
/// use std::collections::HashMap;
///
/// let mut params = HashMap::new();
/// params.insert("algorithm".to_string(), "aes256gcm".to_string());
///
/// let config = EncryptionConfig::from_parameters(&params).unwrap();
/// ```
impl super::stage_service::FromParameters for EncryptionConfig {
    fn from_parameters(params: &std::collections::HashMap<String, String>) -> Result<Self, PipelineError> {
        // Required: algorithm
        let algorithm_str = params
            .get("algorithm")
            .ok_or_else(|| PipelineError::MissingParameter("algorithm".into()))?;

        let algorithm = match algorithm_str.to_lowercase().as_str() {
            "aes256gcm" | "aes-256-gcm" => EncryptionAlgorithm::Aes256Gcm,
            "aes128gcm" | "aes-128-gcm" => EncryptionAlgorithm::Aes128Gcm,
            "chacha20poly1305" | "chacha20-poly1305" => EncryptionAlgorithm::ChaCha20Poly1305,
            other => {
                return Err(PipelineError::InvalidParameter(format!(
                    "Unknown encryption algorithm: {}",
                    other
                )));
            }
        };

        // Optional parameters with defaults
        let key_size = params.get("key_size").and_then(|s| s.parse::<u32>().ok()).unwrap_or(32);

        let iterations = params
            .get("iterations")
            .and_then(|s| s.parse::<u32>().ok())
            .unwrap_or(3);

        Ok(Self {
            algorithm,
            key_derivation: KeyDerivationFunction::Argon2,
            key_size,
            nonce_size: 12,
            salt_size: 16,
            iterations,
            memory_cost: Some(65536), // 64MB default
            parallel_cost: Some(4),
            associated_data: None,
        })
    }
}

impl KeyMaterial {
    /// Sets expiration time
    pub fn with_expiration(mut self, expires_at: chrono::DateTime<chrono::Utc>) -> Self {
        self.expires_at = Some(expires_at);
        self
    }

    /// Checks if key material is expired
    pub fn is_expired(&self) -> bool {
        if let Some(expires_at) = self.expires_at {
            chrono::Utc::now() > expires_at
        } else {
            false
        }
    }

    /// Securely clears key material
    pub fn clear(&mut self) {
        // Zero out sensitive data
        self.key.fill(0);
        self.nonce.fill(0);
        self.salt.fill(0);

        // Clear vectors
        self.key.clear();
        self.nonce.clear();
        self.salt.clear();

        // Shrink to free memory
        self.key.shrink_to_fit();
        self.nonce.shrink_to_fit();
        self.salt.shrink_to_fit();
    }

    /// Gets key size in bytes
    pub fn key_size(&self) -> usize {
        self.key.len()
    }

    /// Gets nonce size in bytes
    pub fn nonce_size(&self) -> usize {
        self.nonce.len()
    }

    /// Gets salt size in bytes
    pub fn salt_size(&self) -> usize {
        self.salt.len()
    }
}

impl Drop for KeyMaterial {
    fn drop(&mut self) {
        self.clear();
    }
}

impl std::fmt::Display for EncryptionAlgorithm {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            EncryptionAlgorithm::Aes256Gcm => write!(f, "AES-256-GCM"),
            EncryptionAlgorithm::ChaCha20Poly1305 => write!(f, "ChaCha20-Poly1305"),
            EncryptionAlgorithm::Aes128Gcm => write!(f, "AES-128-GCM"),
            EncryptionAlgorithm::Aes192Gcm => write!(f, "AES-192-GCM"),
            EncryptionAlgorithm::Custom(name) => write!(f, "Custom({})", name),
        }
    }
}

impl std::fmt::Display for KeyDerivationFunction {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            KeyDerivationFunction::Argon2 => write!(f, "Argon2"),
            KeyDerivationFunction::Scrypt => write!(f, "scrypt"),
            KeyDerivationFunction::Pbkdf2 => write!(f, "PBKDF2"),
            KeyDerivationFunction::Custom(name) => write!(f, "Custom({})", name),
        }
    }
}