oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/side_channel/dpa.py

@@ -0,0 +1,1025 @@
+"""Differential Power Analysis (DPA) framework for side-channel attacks.
+
+This module implements DPA, CPA (Correlation Power Analysis), and Template attacks
+for recovering cryptographic keys from power consumption traces. Supports AES and DES
+with multiple leakage models.
+
+Key capabilities:
+- DPA attack using difference of means
+- CPA attack using Pearson correlation
+- Template attack with profiling and matching phases
+- Multiple leakage models (Hamming weight, Hamming distance, identity)
+- AES S-box and DES operations
+- Visualization of correlation traces and key rankings
+- JSON export of attack results
+
+Typical use cases:
+- Break AES-128 implementations using power analysis
+- Recover DES keys from embedded devices
+- Evaluate cryptographic implementation security
+- Generate attack visualizations for reports
+
+Example:
+    >>> from oscura.side_channel.dpa import DPAAnalyzer, PowerTrace
+    >>> import numpy as np
+    >>> # Create analyzer
+    >>> analyzer = DPAAnalyzer(attack_type="cpa", leakage_model="hamming_weight")
+    >>> # Load power traces with plaintexts
+    >>> traces = [
+    ...     PowerTrace(
+    ...         timestamp=np.arange(1000),
+    ...         power=np.random.randn(1000),
+    ...         plaintext=bytes([i % 256 for i in range(16)])
+    ...     )
+    ...     for _ in range(100)
+    ... ]
+    >>> # Perform attack on first key byte
+    >>> result = analyzer.perform_attack(traces, target_byte=0, algorithm="aes128")
+    >>> print(f"Recovered key byte: 0x{result.recovered_key[0]:02X}")
+    >>> print(f"Confidence: {result.confidence:.2%}")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+
+# AES S-box (forward substitution box)
+AES_SBOX = [
+    0x63,
+    0x7C,
+    0x77,
+    0x7B,
+    0xF2,
+    0x6B,
+    0x6F,
+    0xC5,
+    0x30,
+    0x01,
+    0x67,
+    0x2B,
+    0xFE,
+    0xD7,
+    0xAB,
+    0x76,
+    0xCA,
+    0x82,
+    0xC9,
+    0x7D,
+    0xFA,
+    0x59,
+    0x47,
+    0xF0,
+    0xAD,
+    0xD4,
+    0xA2,
+    0xAF,
+    0x9C,
+    0xA4,
+    0x72,
+    0xC0,
+    0xB7,
+    0xFD,
+    0x93,
+    0x26,
+    0x36,
+    0x3F,
+    0xF7,
+    0xCC,
+    0x34,
+    0xA5,
+    0xE5,
+    0xF1,
+    0x71,
+    0xD8,
+    0x31,
+    0x15,
+    0x04,
+    0xC7,
+    0x23,
+    0xC3,
+    0x18,
+    0x96,
+    0x05,
+    0x9A,
+    0x07,
+    0x12,
+    0x80,
+    0xE2,
+    0xEB,
+    0x27,
+    0xB2,
+    0x75,
+    0x09,
+    0x83,
+    0x2C,
+    0x1A,
+    0x1B,
+    0x6E,
+    0x5A,
+    0xA0,
+    0x52,
+    0x3B,
+    0xD6,
+    0xB3,
+    0x29,
+    0xE3,
+    0x2F,
+    0x84,
+    0x53,
+    0xD1,
+    0x00,
+    0xED,
+    0x20,
+    0xFC,
+    0xB1,
+    0x5B,
+    0x6A,
+    0xCB,
+    0xBE,
+    0x39,
+    0x4A,
+    0x4C,
+    0x58,
+    0xCF,
+    0xD0,
+    0xEF,
+    0xAA,
+    0xFB,
+    0x43,
+    0x4D,
+    0x33,
+    0x85,
+    0x45,
+    0xF9,
+    0x02,
+    0x7F,
+    0x50,
+    0x3C,
+    0x9F,
+    0xA8,
+    0x51,
+    0xA3,
+    0x40,
+    0x8F,
+    0x92,
+    0x9D,
+    0x38,
+    0xF5,
+    0xBC,
+    0xB6,
+    0xDA,
+    0x21,
+    0x10,
+    0xFF,
+    0xF3,
+    0xD2,
+    0xCD,
+    0x0C,
+    0x13,
+    0xEC,
+    0x5F,
+    0x97,
+    0x44,
+    0x17,
+    0xC4,
+    0xA7,
+    0x7E,
+    0x3D,
+    0x64,
+    0x5D,
+    0x19,
+    0x73,
+    0x60,
+    0x81,
+    0x4F,
+    0xDC,
+    0x22,
+    0x2A,
+    0x90,
+    0x88,
+    0x46,
+    0xEE,
+    0xB8,
+    0x14,
+    0xDE,
+    0x5E,
+    0x0B,
+    0xDB,
+    0xE0,
+    0x32,
+    0x3A,
+    0x0A,
+    0x49,
+    0x06,
+    0x24,
+    0x5C,
+    0xC2,
+    0xD3,
+    0xAC,
+    0x62,
+    0x91,
+    0x95,
+    0xE4,
+    0x79,
+    0xE7,
+    0xC8,
+    0x37,
+    0x6D,
+    0x8D,
+    0xD5,
+    0x4E,
+    0xA9,
+    0x6C,
+    0x56,
+    0xF4,
+    0xEA,
+    0x65,
+    0x7A,
+    0xAE,
+    0x08,
+    0xBA,
+    0x78,
+    0x25,
+    0x2E,
+    0x1C,
+    0xA6,
+    0xB4,
+    0xC6,
+    0xE8,
+    0xDD,
+    0x74,
+    0x1F,
+    0x4B,
+    0xBD,
+    0x8B,
+    0x8A,
+    0x70,
+    0x3E,
+    0xB5,
+    0x66,
+    0x48,
+    0x03,
+    0xF6,
+    0x0E,
+    0x61,
+    0x35,
+    0x57,
+    0xB9,
+    0x86,
+    0xC1,
+    0x1D,
+    0x9E,
+    0xE1,
+    0xF8,
+    0x98,
+    0x11,
+    0x69,
+    0xD9,
+    0x8E,
+    0x94,
+    0x9B,
+    0x1E,
+    0x87,
+    0xE9,
+    0xCE,
+    0x55,
+    0x28,
+    0xDF,
+    0x8C,
+    0xA1,
+    0x89,
+    0x0D,
+    0xBF,
+    0xE6,
+    0x42,
+    0x68,
+    0x41,
+    0x99,
+    0x2D,
+    0x0F,
+    0xB0,
+    0x54,
+    0xBB,
+    0x16,
+]
+
+
+@dataclass
+class PowerTrace:
+    """Power consumption trace for side-channel analysis.
+
+    Attributes:
+        timestamp: Time points for each power measurement (seconds or sample index).
+        power: Power consumption measurements (arbitrary units, e.g., voltage).
+        plaintext: Input plaintext for encryption (16 bytes for AES-128).
+        ciphertext: Output ciphertext from encryption (optional).
+        metadata: Additional trace information (device ID, temperature, etc.).
+
+    Example:
+        >>> import numpy as np
+        >>> trace = PowerTrace(
+        ...     timestamp=np.linspace(0, 1e-6, 1000),  # 1 microsecond
+        ...     power=np.random.randn(1000),
+        ...     plaintext=bytes(range(16)),
+        ...     metadata={"device": "STM32", "temperature": 25.0}
+        ... )
+    """
+
+    timestamp: NDArray[np.float64]
+    power: NDArray[np.float64]
+    plaintext: bytes | None = None
+    ciphertext: bytes | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class DPAResult:
+    """Result from DPA/CPA/Template attack.
+
+    Attributes:
+        recovered_key: Recovered key bytes (1 byte for single-byte attack).
+        key_ranks: Correlation or difference-of-means score for each key guess (0-255).
+            Higher values indicate more likely key bytes.
+        correlation_traces: Time x key_guess correlation matrix (optional).
+            Shape: (256, num_samples) for CPA attacks.
+        confidence: Attack confidence score (0.0-1.0).
+            Based on separation between best and second-best key guess.
+        successful: True if attack confidence exceeds threshold (>0.7).
+
+    Example:
+        >>> result = analyzer.perform_attack(traces, target_byte=0)
+        >>> if result.successful:
+        ...     print(f"Key: 0x{result.recovered_key.hex()}")
+        ...     print(f"Confidence: {result.confidence:.2%}")
+        ... else:
+        ...     print("Attack failed - need more traces")
+    """
+
+    recovered_key: bytes
+    key_ranks: NDArray[np.float64]
+    correlation_traces: NDArray[np.float64] | None = None
+    confidence: float = 0.0
+    successful: bool = False
+
+
+class DPAAnalyzer:
+    """Differential Power Analysis framework for cryptographic key recovery.
+
+    This class implements multiple power analysis attack methods for recovering
+    secret keys from power consumption traces. Supports DPA, CPA, and Template
+    attacks with various leakage models.
+
+    Attack Types:
+        dpa: Classic DPA using difference of means (Kocher et al., 1999)
+        cpa: Correlation Power Analysis (Brier et al., 2004)
+        template: Template attack with profiling phase (Chari et al., 2003)
+
+    Leakage Models:
+        hamming_weight: Power proportional to number of 1 bits (most common)
+        hamming_distance: Power proportional to bit transitions
+        identity: Direct intermediate value (linear leakage)
+
+    Supported Algorithms:
+        aes128: AES-128 encryption (16-byte key)
+        des: DES encryption (8-byte key, not implemented yet)
+
+    Example:
+        >>> # Basic CPA attack on AES
+        >>> analyzer = DPAAnalyzer(attack_type="cpa", leakage_model="hamming_weight")
+        >>> result = analyzer.perform_attack(traces, target_byte=0)
+        >>> # Template attack (profiling + matching)
+        >>> analyzer_template = DPAAnalyzer(attack_type="template")
+        >>> result = analyzer_template.template_attack(
+        ...     profiling_traces=train_traces,
+        ...     attack_traces=test_traces,
+        ...     target_byte=0
+        ... )
+    """
+
+    LEAKAGE_MODELS: ClassVar[list[str]] = ["hamming_weight", "hamming_distance", "identity"]
+    ATTACK_TYPES: ClassVar[list[str]] = ["dpa", "cpa", "template"]
+
+    def __init__(
+        self,
+        attack_type: str = "cpa",
+        leakage_model: str = "hamming_weight",
+    ) -> None:
+        """Initialize DPA analyzer.
+
+        Args:
+            attack_type: Attack method ("dpa", "cpa", "template").
+            leakage_model: Power leakage model ("hamming_weight", "hamming_distance",
+                "identity").
+
+        Raises:
+            ValueError: If attack_type or leakage_model is invalid.
+
+        Example:
+            >>> analyzer = DPAAnalyzer(attack_type="cpa")
+            >>> analyzer = DPAAnalyzer(
+            ...     attack_type="template",
+            ...     leakage_model="hamming_distance"
+            ... )
+        """
+        if attack_type not in self.ATTACK_TYPES:
+            msg = f"Invalid attack_type: {attack_type}. Must be one of {self.ATTACK_TYPES}"
+            raise ValueError(msg)
+
+        if leakage_model not in self.LEAKAGE_MODELS:
+            msg = f"Invalid leakage_model: {leakage_model}. Must be one of {self.LEAKAGE_MODELS}"
+            raise ValueError(msg)
+
+        self.attack_type = attack_type
+        self.leakage_model = leakage_model
+        # Templates: key_byte -> (mean vector, covariance matrix)
+        self.templates: dict[int, tuple[NDArray[np.float64], NDArray[np.float64]]] = {}
+
+    def perform_attack(
+        self,
+        traces: list[PowerTrace],
+        target_byte: int = 0,
+        algorithm: str = "aes128",
+    ) -> DPAResult:
+        """Perform power analysis attack to recover key byte.
+
+        Dispatches to appropriate attack method based on attack_type.
+
+        Args:
+            traces: List of power traces with plaintexts.
+            target_byte: Target key byte position (0-15 for AES-128).
+            algorithm: Cryptographic algorithm ("aes128" or "des").
+
+        Returns:
+            DPAResult with recovered key and confidence metrics.
+
+        Raises:
+            ValueError: If traces is empty, target_byte invalid, or algorithm unsupported.
+
+        Example:
+            >>> result = analyzer.perform_attack(traces, target_byte=0)
+            >>> print(f"Key byte {0}: 0x{result.recovered_key[0]:02X}")
+        """
+        if not traces:
+            raise ValueError("No traces provided")
+
+        if target_byte < 0 or target_byte >= 16:
+            raise ValueError(f"Invalid target_byte: {target_byte}. Must be 0-15 for AES-128")
+
+        if algorithm != "aes128":
+            raise ValueError(f"Unsupported algorithm: {algorithm}. Only 'aes128' implemented")
+
+        if self.attack_type == "dpa":
+            return self.dpa_attack(traces, target_byte)
+        elif self.attack_type == "cpa":
+            return self.cpa_attack(traces, target_byte)
+        else:
+            msg = "Template attack requires separate profiling/attack traces"
+            raise ValueError(msg)
+
+    def dpa_attack(
+        self,
+        traces: list[PowerTrace],
+        target_byte: int,
+    ) -> DPAResult:
+        """Classic DPA attack using difference of means.
+
+        Separates traces into two groups based on hypothetical intermediate bit value,
+        then computes difference of mean power consumption at each time point.
+
+        Algorithm:
+            1. For each key guess k in [0, 255]:
+                a. Compute intermediate value for each trace: v = SBOX[plaintext ^ k]
+                b. Partition traces by bit b of v (e.g., LSB)
+                c. Compute differential trace: mean(power | b=1) - mean(power | b=0)
+                d. Score = max absolute value in differential trace
+            2. Return key with highest score
+
+        Args:
+            traces: List of power traces with plaintexts.
+            target_byte: Target key byte position.
+
+        Returns:
+            DPAResult with recovered key byte.
+
+        Example:
+            >>> analyzer = DPAAnalyzer(attack_type="dpa")
+            >>> result = analyzer.dpa_attack(traces, target_byte=0)
+        """
+        if not traces:
+            raise ValueError("No traces provided")
+
+        # Extract plaintexts and power matrix
+        plaintexts = [t.plaintext for t in traces if t.plaintext]
+        if not plaintexts:
+            raise ValueError("No plaintexts in traces")
+
+        power_matrix = np.array([t.power for t in traces])  # (num_traces, num_samples)
+
+        # Attack each key guess
+        max_diffs = np.zeros(256)
+
+        for key_guess in range(256):
+            # Compute intermediate values and selection bit
+            intermediates = []
+            for plaintext in plaintexts:
+                if plaintext is None or target_byte >= len(plaintext):
+                    intermediates.append(0)
+                    continue
+                intermediate = self._aes_sbox_output(plaintext[target_byte], key_guess)
+                intermediates.append(intermediate)
+
+            # Use LSB as selection bit
+            selection_bits = np.array([v & 1 for v in intermediates])
+
+            # Partition traces
+            group0_traces = power_matrix[selection_bits == 0]
+            group1_traces = power_matrix[selection_bits == 1]
+
+            if len(group0_traces) == 0 or len(group1_traces) == 0:
+                continue
+
+            # Compute differential trace
+            mean0 = np.mean(group0_traces, axis=0)
+            mean1 = np.mean(group1_traces, axis=0)
+            diff = mean1 - mean0
+
+            # Score is maximum absolute difference
+            max_diffs[key_guess] = np.max(np.abs(diff))
+
+        # Find best key guess
+        recovered_key_byte = int(np.argmax(max_diffs))
+        max_score = max_diffs[recovered_key_byte]
+
+        # Calculate confidence (separation from second-best)
+        sorted_scores = np.sort(max_diffs)
+        if sorted_scores[-2] > 0:
+            confidence = 1.0 - (sorted_scores[-2] / max_score)
+        else:
+            confidence = 1.0
+
+        successful = confidence > 0.7
+
+        return DPAResult(
+            recovered_key=bytes([recovered_key_byte]),
+            key_ranks=max_diffs,
+            correlation_traces=None,
+            confidence=float(confidence),
+            successful=successful,
+        )
+
+    def cpa_attack(
+        self,
+        traces: list[PowerTrace],
+        target_byte: int,
+    ) -> DPAResult:
+        """Correlation Power Analysis (CPA) attack.
+
+        Computes Pearson correlation between hypothetical power consumption (based on
+        leakage model) and measured power at each time point. Key with highest
+        correlation is most likely correct.
+
+        Algorithm:
+            1. For each key guess k in [0, 255]:
+                a. Compute hypothetical power: h[i] = LeakageModel(SBOX[plaintext[i] ^ k])
+                b. For each time point t:
+                    - Compute correlation: corr(h, power[:, t])
+                c. Score = max |correlation| across all time points
+            2. Return key with highest score
+
+        Args:
+            traces: List of power traces with plaintexts.
+            target_byte: Target key byte position.
+
+        Returns:
+            DPAResult with recovered key byte and correlation traces.
+
+        Example:
+            >>> analyzer = DPAAnalyzer(attack_type="cpa", leakage_model="hamming_weight")
+            >>> result = analyzer.cpa_attack(traces, target_byte=0)
+            >>> print(f"Max correlation: {result.confidence:.3f}")
+        """
+        if not traces:
+            raise ValueError("No traces provided")
+
+        # Extract plaintexts and power matrix
+        plaintexts = [t.plaintext for t in traces if t.plaintext]
+        if not plaintexts:
+            raise ValueError("No plaintexts in traces")
+
+        power_matrix = np.array([t.power for t in traces])  # (num_traces, num_samples)
+        num_samples = power_matrix.shape[1]
+
+        # Attack each key guess
+        correlation_traces = np.zeros((256, num_samples))
+
+        for key_guess in range(256):
+            # Calculate hypothetical power consumption
+            hypothetical = self._calculate_hypothetical_power(
+                plaintexts,
+                key_guess,
+                target_byte,
+            )
+
+            # Calculate correlation at each time point
+            for sample_idx in range(num_samples):
+                measured = power_matrix[:, sample_idx]
+                # Use numpy's correlation coefficient
+                corr_matrix = np.corrcoef(hypothetical, measured)
+                correlation = corr_matrix[0, 1] if corr_matrix.shape == (2, 2) else 0.0
+                # Handle NaN from constant signals
+                if np.isnan(correlation):
+                    correlation = 0.0
+                correlation_traces[key_guess, sample_idx] = abs(correlation)
+
+        # Find key guess with maximum correlation
+        max_correlations = np.max(correlation_traces, axis=1)
+        recovered_key_byte = int(np.argmax(max_correlations))
+        max_correlation = max_correlations[recovered_key_byte]
+
+        # Calculate confidence (separation from second-best)
+        sorted_corrs = np.sort(max_correlations)
+        if sorted_corrs[-2] > 0:
+            confidence = 1.0 - (sorted_corrs[-2] / max_correlation)
+        else:
+            confidence = 1.0
+
+        # Check if attack successful (correlation > threshold)
+        successful = max_correlation > 0.7
+
+        return DPAResult(
+            recovered_key=bytes([recovered_key_byte]),
+            key_ranks=max_correlations,
+            correlation_traces=correlation_traces,
+            confidence=float(confidence),
+            successful=successful,
+        )
+
+    def template_attack(
+        self,
+        profiling_traces: list[PowerTrace],
+        attack_traces: list[PowerTrace],
+        target_byte: int,
+    ) -> DPAResult:
+        """Template attack with profiling and matching phases.
+
+        Phase 1 (Profiling): Build templates (mean, covariance) for each key byte
+            using traces from controlled device with known key.
+        Phase 2 (Matching): Match attack traces to templates using multivariate
+            Gaussian probability.
+
+        Args:
+            profiling_traces: Traces from device with known key for template building.
+            attack_traces: Traces from target device with unknown key.
+            target_byte: Target key byte position.
+
+        Returns:
+            DPAResult with recovered key byte.
+
+        Raises:
+            ValueError: If profiling or attack traces are empty.
+
+        Example:
+            >>> analyzer = DPAAnalyzer(attack_type="template")
+            >>> # Build templates with known key
+            >>> result = analyzer.template_attack(
+            ...     profiling_traces=train_traces,
+            ...     attack_traces=test_traces,
+            ...     target_byte=0
+            ... )
+        """
+        if not profiling_traces or not attack_traces:
+            raise ValueError("Both profiling and attack traces required")
+
+        # Phase 1: Build templates from profiling traces
+        self._build_templates(profiling_traces, target_byte)
+
+        # Phase 2: Match attack traces to templates
+        power_matrix = np.array([t.power for t in attack_traces])
+        num_samples = power_matrix.shape[1]
+
+        # Calculate probability for each key guess
+        probabilities = np.zeros(256)
+
+        for key_guess in range(256):
+            if key_guess not in self.templates:
+                continue
+
+            mean, cov = self.templates[key_guess]
+
+            # Use only points of interest (reduce dimensionality)
+            # For simplicity, use first min(100, num_samples) points
+            poi_count = min(100, num_samples)
+            mean_poi = mean[:poi_count]
+            cov_poi = cov[:poi_count, :poi_count]
+
+            # Add small regularization to covariance
+            cov_poi = cov_poi + np.eye(poi_count) * 1e-6
+
+            # Calculate log probability for each trace
+            log_prob = 0.0
+            for trace in power_matrix:
+                trace_poi = trace[:poi_count]
+                try:
+                    # Multivariate Gaussian log probability
+                    diff = trace_poi - mean_poi
+                    inv_cov = np.linalg.inv(cov_poi)
+                    log_prob += -0.5 * (diff @ inv_cov @ diff)
+                except np.linalg.LinAlgError:
+                    # Singular covariance matrix
+                    log_prob += -1e10
+
+            probabilities[key_guess] = log_prob
+
+        # Find best key guess
+        recovered_key_byte = int(np.argmax(probabilities))
+        max_prob = probabilities[recovered_key_byte]
+
+        # Calculate confidence
+        sorted_probs = np.sort(probabilities)
+        if sorted_probs[-2] != -np.inf and max_prob != -np.inf and max_prob != 0:
+            # Use absolute difference for log probabilities (negative values)
+            confidence = abs(max_prob - sorted_probs[-2]) / (abs(max_prob) + 1e-10)
+            confidence = min(confidence, 1.0)
+        else:
+            confidence = 0.0
+
+        successful = confidence > 0.7
+
+        return DPAResult(
+            recovered_key=bytes([recovered_key_byte]),
+            key_ranks=probabilities,
+            correlation_traces=None,
+            confidence=float(confidence),
+            successful=successful,
+        )
+
+    def _build_templates(
+        self,
+        traces: list[PowerTrace],
+        target_byte: int,
+    ) -> None:
+        """Build templates from profiling traces with known key.
+
+        Args:
+            traces: Profiling traces with known plaintexts and ciphertexts.
+            target_byte: Target key byte position.
+        """
+        # Group traces by intermediate value (assuming key byte = 0 for profiling)
+        # In real scenario, you'd know the profiling key
+        profiling_key_byte = 0  # Known key for profiling device
+
+        groups: dict[int, list[NDArray[np.float64]]] = {}
+
+        for trace in traces:
+            if trace.plaintext is None or target_byte >= len(trace.plaintext):
+                continue
+
+            intermediate = self._aes_sbox_output(
+                trace.plaintext[target_byte],
+                profiling_key_byte,
+            )
+
+            if intermediate not in groups:
+                groups[intermediate] = []
+            groups[intermediate].append(trace.power)
+
+        # Build template for each intermediate value
+        for intermediate, power_traces in groups.items():
+            if len(power_traces) < 2:
+                continue
+
+            power_array = np.array(power_traces)
+            mean = np.mean(power_array, axis=0)
+            cov = np.cov(power_array.T)
+
+            self.templates[intermediate] = (mean, cov)
+
+    def _hamming_weight(self, value: int) -> int:
+        """Calculate Hamming weight (population count).
+
+        Args:
+            value: Integer value (0-255).
+
+        Returns:
+            Number of 1 bits in binary representation (0-8).
+
+        Example:
+            >>> analyzer._hamming_weight(0x0F)  # 0b00001111
+            4
+            >>> analyzer._hamming_weight(0xFF)  # 0b11111111
+            8
+        """
+        count = 0
+        while value:
+            count += value & 1
+            value >>= 1
+        return count
+
+    def _hamming_distance(self, value1: int, value2: int) -> int:
+        """Calculate Hamming distance between two values.
+
+        Args:
+            value1: First integer value (0-255).
+            value2: Second integer value (0-255).
+
+        Returns:
+            Number of differing bits (0-8).
+
+        Example:
+            >>> analyzer._hamming_distance(0x00, 0xFF)
+            8
+            >>> analyzer._hamming_distance(0x0F, 0x0E)  # differ in 1 bit
+            1
+        """
+        return self._hamming_weight(value1 ^ value2)
+
+    def _aes_sbox_output(self, plaintext_byte: int, key_guess: int) -> int:
+        """Calculate AES S-box output for given plaintext and key guess.
+
+        Args:
+            plaintext_byte: Single plaintext byte (0-255).
+            key_guess: Key byte guess (0-255).
+
+        Returns:
+            S-box output (0-255).
+
+        Example:
+            >>> analyzer._aes_sbox_output(0x00, 0x00)
+            99  # SBOX[0x00] = 0x63
+        """
+        xored = plaintext_byte ^ key_guess
+        return AES_SBOX[xored]
+
+    def _calculate_hypothetical_power(
+        self,
+        plaintexts: Sequence[bytes | None],
+        key_guess: int,
+        target_byte: int,
+    ) -> NDArray[np.float64]:
+        """Calculate hypothetical power consumption for key guess.
+
+        Uses configured leakage model to convert intermediate values to
+        hypothetical power consumption.
+
+        Args:
+            plaintexts: List of plaintext bytes.
+            key_guess: Key byte guess (0-255).
+            target_byte: Target byte position.
+
+        Returns:
+            Array of hypothetical power values.
+
+        Example:
+            >>> hyp_power = analyzer._calculate_hypothetical_power(
+            ...     plaintexts=[b'\\x00\\x01\\x02...'],
+            ...     key_guess=0x42,
+            ...     target_byte=0
+            ... )
+        """
+        hypothetical = []
+
+        for plaintext in plaintexts:
+            if plaintext is None or target_byte >= len(plaintext):
+                hypothetical.append(0.0)
+                continue
+
+            # Calculate intermediate value (AES S-box output)
+            intermediate = self._aes_sbox_output(plaintext[target_byte], key_guess)
+
+            # Apply leakage model
+            if self.leakage_model == "hamming_weight":
+                power = float(self._hamming_weight(intermediate))
+            elif self.leakage_model == "hamming_distance":
+                # Hamming distance from plaintext to intermediate
+                power = float(self._hamming_distance(plaintext[target_byte], intermediate))
+            else:  # identity
+                power = float(intermediate)
+
+            hypothetical.append(power)
+
+        return np.array(hypothetical)
+
+    def visualize_attack(
+        self,
+        result: DPAResult,
+        output_path: Path,
+    ) -> None:
+        """Visualize CPA attack results with correlation traces and key rankings.
+
+        Creates two-panel plot:
+            - Top: Correlation traces for all key guesses (highlighted for recovered key)
+            - Bottom: Bar chart of maximum correlation per key guess
+
+        Args:
+            result: DPAResult from CPA attack.
+            output_path: Path to save plot image (PNG format).
+
+        Raises:
+            ValueError: If correlation_traces is None (not a CPA attack).
+            ImportError: If matplotlib is not installed.
+
+        Example:
+            >>> result = analyzer.cpa_attack(traces, target_byte=0)
+            >>> analyzer.visualize_attack(result, Path("attack_plot.png"))
+        """
+        if result.correlation_traces is None:
+            raise ValueError("Visualization requires correlation_traces (use CPA attack)")
+
+        try:
+            import matplotlib.pyplot as plt
+        except ImportError as e:
+            msg = "matplotlib required for visualization"
+            raise ImportError(msg) from e
+
+        fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(12, 8))
+
+        # Plot 1: Correlation traces for all key guesses
+        for key_guess in range(256):
+            ax1.plot(
+                result.correlation_traces[key_guess],
+                alpha=0.1,
+                color="blue",
+            )
+
+        # Highlight correct key
+        recovered = result.recovered_key[0]
+        ax1.plot(
+            result.correlation_traces[recovered],
+            color="red",
+            linewidth=2,
+            label=f"Recovered key: 0x{recovered:02X}",
+        )
+
+        ax1.set_xlabel("Sample point")
+        ax1.set_ylabel("|Correlation|")
+        ax1.set_title("Correlation traces for all key guesses")
+        ax1.legend()
+        ax1.grid(True, alpha=0.3)
+
+        # Plot 2: Key ranking (max correlation per key)
+        ax2.bar(range(256), result.key_ranks, color="blue", alpha=0.6)
+        ax2.axvline(
+            result.recovered_key[0],
+            color="red",
+            linestyle="--",
+            linewidth=2,
+            label="Recovered key",
+        )
+        ax2.set_xlabel("Key guess")
+        ax2.set_ylabel("Max |Correlation|")
+        ax2.set_title("Key ranking")
+        ax2.legend()
+        ax2.grid(True, alpha=0.3)
+
+        plt.tight_layout()
+        plt.savefig(output_path, dpi=300, bbox_inches="tight")
+        plt.close()
+
+        logger.info(f"Attack visualization saved to {output_path}")
+
+    def export_results(
+        self,
+        result: DPAResult,
+        output_path: Path,
+    ) -> None:
+        """Export attack results to JSON file.
+
+        Args:
+            result: DPAResult from attack.
+            output_path: Path to save JSON file.
+
+        Example:
+            >>> result = analyzer.perform_attack(traces, target_byte=0)
+            >>> analyzer.export_results(result, Path("attack_results.json"))
+        """
+        data = {
+            "recovered_key": result.recovered_key.hex(),
+            "confidence": result.confidence,
+            "successful": result.successful,
+            "key_ranks": result.key_ranks.tolist(),
+            "attack_type": self.attack_type,
+            "leakage_model": self.leakage_model,
+        }
+
+        if result.correlation_traces is not None:
+            # Only export max correlations to reduce file size
+            data["max_correlations"] = np.max(result.correlation_traces, axis=1).tolist()
+
+        with open(output_path, "w") as f:
+            json.dump(data, f, indent=2)
+
+        logger.info(f"Attack results exported to {output_path}")