oscura 0.1.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

oscura/loaders/chipwhisperer.py

@@ -0,0 +1,393 @@
+"""ChipWhisperer trace loader.
+
+This module loads power/EM traces from ChipWhisperer capture files (.npy, .trs).
+
+ChipWhisperer is a widely-used open-source platform for side-channel analysis
+and hardware security testing.
+
+Example:
+    >>> from oscura.loaders.chipwhisperer import load_chipwhisperer
+    >>> traces, metadata = load_chipwhisperer("capture_data.npy")
+    >>> print(f"Loaded {len(traces)} traces")
+
+References:
+    ChipWhisperer Project: https://github.com/newaetech/chipwhisperer
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from oscura.core.exceptions import FormatError, LoaderError
+from oscura.core.types import TraceMetadata, WaveformTrace
+
+if TYPE_CHECKING:
+    from os import PathLike
+
+    from numpy.typing import NDArray
+
+__all__ = [
+    "ChipWhispererTraceSet",
+    "load_chipwhisperer",
+    "load_chipwhisperer_npy",
+    "load_chipwhisperer_trs",
+]
+
+
+@dataclass
+class ChipWhispererTraceSet:
+    """ChipWhisperer trace set container.
+
+    Attributes:
+        traces: Power/EM traces (n_traces, n_samples).
+        plaintexts: Input plaintexts (n_traces, plaintext_size).
+        ciphertexts: Output ciphertexts (n_traces, ciphertext_size).
+        keys: Encryption keys if known (n_traces, key_size).
+        sample_rate: Sample rate in Hz.
+        metadata: Additional metadata.
+    """
+
+    traces: NDArray[np.floating[Any]]
+    plaintexts: NDArray[np.integer[Any]] | None = None
+    ciphertexts: NDArray[np.integer[Any]] | None = None
+    keys: NDArray[np.integer[Any]] | None = None
+    sample_rate: float = 1e6
+    metadata: dict[str, object] | None = None
+
+    @property
+    def n_traces(self) -> int:
+        """Number of traces."""
+        return int(self.traces.shape[0])
+
+    @property
+    def n_samples(self) -> int:
+        """Number of samples per trace."""
+        return int(self.traces.shape[1])
+
+
+def load_chipwhisperer(
+    path: str | PathLike[str],
+    *,
+    sample_rate: float | None = None,
+) -> ChipWhispererTraceSet:
+    """Load ChipWhisperer traces from file.
+
+    Auto-detects file format (.npy, .trs) and delegates to appropriate loader.
+
+    Args:
+        path: Path to ChipWhisperer trace file.
+        sample_rate: Override sample rate (if not in file).
+
+    Returns:
+        ChipWhispererTraceSet with traces and metadata.
+
+    Raises:
+        LoaderError: If file cannot be loaded.
+        FormatError: If file format invalid.
+
+    Example:
+        >>> traceset = load_chipwhisperer("traces.npy")
+        >>> print(f"Loaded {traceset.n_traces} traces")
+        >>> print(f"Samples per trace: {traceset.n_samples}")
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise LoaderError("File not found", file_path=str(path))
+
+    ext = path.suffix.lower()
+
+    if ext == ".npy":
+        return load_chipwhisperer_npy(path, sample_rate=sample_rate)
+    elif ext == ".trs":
+        return load_chipwhisperer_trs(path, sample_rate=sample_rate)
+    else:
+        raise FormatError(
+            f"Unsupported ChipWhisperer format: {ext}",
+            file_path=str(path),
+            expected=".npy or .trs",
+            got=ext,
+        )
+
+
+def load_chipwhisperer_npy(
+    path: str | PathLike[str],
+    *,
+    sample_rate: float | None = None,
+) -> ChipWhispererTraceSet:
+    """Load ChipWhisperer traces from .npy file.
+
+    ChipWhisperer often saves trace data as numpy .npy files with
+    associated metadata in .npy files (textin.npy, textout.npy, etc.).
+
+    Args:
+        path: Path to traces .npy file.
+        sample_rate: Override sample rate.
+
+    Returns:
+        ChipWhispererTraceSet with traces and metadata.
+
+    Raises:
+        LoaderError: If file cannot be loaded.
+
+    Example:
+        >>> traceset = load_chipwhisperer_npy("traces.npy")
+        >>> # Look for associated files
+        >>> if traceset.plaintexts is not None:
+        ...     print("Plaintexts available")
+    """
+    path = Path(path)
+    base_path = path.parent
+    base_name = path.stem
+
+    try:
+        # Load main trace data
+        traces = np.load(path)
+
+        # Ensure 2D array (n_traces, n_samples)
+        if traces.ndim == 1:
+            traces = traces.reshape(1, -1)
+        elif traces.ndim > 2:
+            raise FormatError(
+                f"Expected 1D or 2D trace array, got {traces.ndim}D",
+                file_path=str(path),
+            )
+
+    except (OSError, ValueError) as e:
+        # Catch file I/O errors, but let FormatError propagate
+        raise LoaderError(
+            "Failed to load trace file",
+            file_path=str(path),
+            details=str(e),
+        ) from e
+
+    # Try to load associated files (common ChipWhisperer naming)
+    plaintexts = None
+    ciphertexts = None
+    keys = None
+
+    # Look for textin.npy (plaintexts)
+    textin_path = base_path / f"{base_name}_textin.npy"
+    if not textin_path.exists():
+        textin_path = base_path / "textin.npy"
+    if textin_path.exists():
+        try:
+            plaintexts = np.load(textin_path)
+        except Exception:
+            pass  # Optional metadata file, silently ignore if missing or corrupt  # Not critical
+
+    # Look for textout.npy (ciphertexts)
+    textout_path = base_path / f"{base_name}_textout.npy"
+    if not textout_path.exists():
+        textout_path = base_path / "textout.npy"
+    if textout_path.exists():
+        try:
+            ciphertexts = np.load(textout_path)
+        except Exception:
+            pass
+
+    # Look for keys.npy
+    keys_path = base_path / f"{base_name}_keys.npy"
+    if not keys_path.exists():
+        keys_path = base_path / "keys.npy"
+    if keys_path.exists():
+        try:
+            keys = np.load(keys_path)
+        except Exception:
+            pass  # Optional metadata file, silently ignore if corrupt
+
+    # Use default sample rate if not specified
+    if sample_rate is None:
+        sample_rate = 1e6  # Default 1 MS/s
+
+    return ChipWhispererTraceSet(
+        traces=traces.astype(np.float64),
+        plaintexts=plaintexts.astype(np.uint8) if plaintexts is not None else None,
+        ciphertexts=ciphertexts.astype(np.uint8) if ciphertexts is not None else None,
+        keys=keys.astype(np.uint8) if keys is not None else None,
+        sample_rate=sample_rate,
+        metadata={
+            "source_file": str(path),
+            "format": "chipwhisperer_npy",
+        },
+    )
+
+
+def load_chipwhisperer_trs(
+    path: str | PathLike[str],
+    *,
+    sample_rate: float | None = None,
+) -> ChipWhispererTraceSet:
+    """Load ChipWhisperer traces from Inspector .trs file.
+
+    The .trs format is used by Riscure Inspector and supported by ChipWhisperer.
+
+    TRS file structure:
+    - Header with metadata
+    - Trace data (interleaved with trace-specific data)
+
+    Args:
+        path: Path to .trs file.
+        sample_rate: Override sample rate.
+
+    Returns:
+        ChipWhispererTraceSet with traces and metadata.
+
+    Raises:
+        LoaderError: If file cannot be loaded.
+        FormatError: If TRS format invalid.
+
+    Example:
+        >>> traceset = load_chipwhisperer_trs("capture.trs")
+        >>> print(f"Loaded {traceset.n_traces} traces")
+
+    References:
+        Inspector Trace Set (.trs) file format specification
+    """
+    path = Path(path)
+
+    try:
+        with open(path, "rb") as f:
+            # Read TRS header
+            # Tag-Length-Value structure
+            tags = {}
+
+            while True:
+                tag_byte = f.read(1)
+                if not tag_byte or tag_byte == b"\x5f":  # End of header
+                    break
+
+                tag = tag_byte[0]
+                length = int.from_bytes(f.read(1), byteorder="little")
+
+                # Extended length for large values
+                if length == 0xFF:
+                    length = int.from_bytes(f.read(4), byteorder="little")
+
+                value = f.read(length)
+                tags[tag] = value
+
+            # Parse critical tags
+            # 0x41: Number of traces
+            n_traces = int.from_bytes(tags.get(0x41, b"\x00\x00"), byteorder="little")
+
+            # 0x42: Number of samples per trace
+            n_samples = int.from_bytes(tags.get(0x42, b"\x00\x00"), byteorder="little")
+
+            # 0x43: Sample coding (1=byte, 2=short, 4=float)
+            sample_coding = tags.get(0x43, b"\x01")[0]
+
+            # 0x44: Data length (plaintext/ciphertext)
+            data_length = int.from_bytes(tags.get(0x44, b"\x00\x00"), byteorder="little")
+
+            if n_traces == 0 or n_samples == 0:
+                raise FormatError(
+                    "Invalid TRS file: zero traces or samples",
+                    file_path=str(path),
+                )
+
+            # Determine numpy dtype from sample coding
+            dtype: type[np.int8] | type[np.int16] | type[np.float32]
+            if sample_coding == 1:
+                dtype = np.int8
+            elif sample_coding == 2:
+                dtype = np.int16
+            elif sample_coding == 4:
+                dtype = np.float32
+            else:
+                raise FormatError(
+                    f"Unsupported sample coding: {sample_coding}",
+                    file_path=str(path),
+                )
+
+            # Read traces
+            traces = np.zeros((n_traces, n_samples), dtype=np.float64)
+            plaintexts = (
+                np.zeros((n_traces, data_length), dtype=np.uint8) if data_length > 0 else None
+            )
+            ciphertexts = None  # Not typically in TRS files
+
+            for trace_idx in range(n_traces):
+                # Read trace-specific data (plaintext/key)
+                if data_length > 0:
+                    trace_data = np.frombuffer(f.read(data_length), dtype=np.uint8)
+                    if plaintexts is not None:
+                        plaintexts[trace_idx] = trace_data
+
+                # Read trace samples
+                trace_samples = np.frombuffer(f.read(n_samples * dtype(0).itemsize), dtype=dtype)
+                traces[trace_idx] = trace_samples.astype(np.float64)
+
+    except OSError as e:
+        raise LoaderError(
+            "Failed to read TRS file",
+            file_path=str(path),
+            details=str(e),
+        ) from e
+    except Exception as e:
+        if isinstance(e, (LoaderError, FormatError)):
+            raise
+        raise LoaderError(
+            "Failed to parse TRS file",
+            file_path=str(path),
+            details=str(e),
+        ) from e
+
+    # Use default sample rate if not specified
+    if sample_rate is None:
+        sample_rate = 1e6  # Default 1 MS/s
+
+    return ChipWhispererTraceSet(
+        traces=traces,
+        plaintexts=plaintexts,
+        ciphertexts=ciphertexts,
+        keys=None,
+        sample_rate=sample_rate,
+        metadata={
+            "source_file": str(path),
+            "format": "chipwhisperer_trs",
+            "n_traces": n_traces,
+            "n_samples": n_samples,
+            "sample_coding": sample_coding,
+        },
+    )
+
+
+def to_waveform_trace(
+    traceset: ChipWhispererTraceSet,
+    trace_index: int = 0,
+) -> WaveformTrace:
+    """Convert ChipWhisperer trace to WaveformTrace.
+
+    Args:
+        traceset: ChipWhisperer trace set.
+        trace_index: Index of trace to convert.
+
+    Returns:
+        WaveformTrace for single trace.
+
+    Raises:
+        IndexError: If trace_index out of range.
+
+    Example:
+        >>> traceset = load_chipwhisperer("traces.npy")
+        >>> trace = to_waveform_trace(traceset, trace_index=0)
+        >>> print(f"Sample rate: {trace.metadata.sample_rate} Hz")
+    """
+    if not 0 <= trace_index < traceset.n_traces:
+        raise IndexError(f"trace_index {trace_index} out of range [0, {traceset.n_traces})")
+
+    metadata = TraceMetadata(
+        sample_rate=traceset.sample_rate,
+        source_file=str(traceset.metadata.get("source_file", "")) if traceset.metadata else "",
+        channel_name=f"trace_{trace_index}",
+    )
+
+    return WaveformTrace(
+        data=traceset.traces[trace_index],
+        metadata=metadata,
+    )

oscura/loaders/pcap.py

@@ -27,7 +27,7 @@ if TYPE_CHECKING:
 
 # Try to import dpkt for full PCAP support
 try:
-    import dpkt  # type: ignore[import-untyped]
+    import dpkt  # type: ignore[import-not-found]
 
     DPKT_AVAILABLE = True
 except ImportError:

oscura/loaders/touchstone.py

@@ -0,0 +1,221 @@
+"""Touchstone file loader for S-parameter data.
+
+Supports .s1p through .s8p formats (Touchstone 1.0 and 2.0).
+
+Example:
+    >>> from oscura.loaders import load_touchstone
+    >>> s_params = load_touchstone("cable.s2p")
+    >>> print(f"Loaded {s_params.n_ports}-port, {len(s_params.frequencies)} points")
+
+References:
+    Touchstone 2.0 File Format Specification
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+from pathlib import Path
+
+import numpy as np
+
+from oscura.analyzers.signal_integrity.sparams import SParameterData
+from oscura.core.exceptions import FormatError, LoaderError
+
+
+def load_touchstone(path: str | Path) -> SParameterData:
+    """Load S-parameter data from Touchstone file.
+
+    Supports .s1p through .s8p formats and both Touchstone 1.0
+    and 2.0 file formats.
+
+    Args:
+        path: Path to Touchstone file.
+
+    Returns:
+        SParameterData with loaded S-parameters.
+
+    Raises:
+        LoaderError: If file cannot be read.
+        FormatError: If file format is invalid.
+
+    Example:
+        >>> s_params = load_touchstone("cable.s2p")
+        >>> print(f"Loaded {s_params.n_ports}-port, {len(s_params.frequencies)} points")
+
+    References:
+        Touchstone 2.0 File Format Specification
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise LoaderError(f"File not found: {path}")
+
+    # Determine number of ports from extension
+    suffix = path.suffix.lower()
+    match = re.match(r"\.s(\d+)p", suffix)
+    if not match:
+        raise FormatError(f"Unsupported file extension: {suffix}")
+
+    n_ports = int(match.group(1))
+
+    try:
+        with open(path) as f:
+            lines = f.readlines()
+    except Exception as e:
+        raise LoaderError(f"Failed to read file: {e}")  # noqa: B904
+
+    return _parse_touchstone(lines, n_ports, str(path))
+
+
+def _parse_touchstone(
+    lines: list[str],
+    n_ports: int,
+    source_file: str,
+) -> SParameterData:
+    """Parse Touchstone file content.
+
+    Args:
+        lines: File lines.
+        n_ports: Number of ports.
+        source_file: Source file path.
+
+    Returns:
+        Parsed SParameterData.
+
+    Raises:
+        FormatError: If file format is invalid.
+    """
+    comments = []
+    option_line = None
+    data_lines = []
+
+    for line in lines:
+        line = line.strip()
+
+        if not line:
+            continue
+
+        if line.startswith("!"):
+            comments.append(line[1:].strip())
+        elif line.startswith("#"):
+            option_line = line
+        else:
+            data_lines.append(line)
+
+    # Parse option line
+    freq_unit = 1e9  # Default GHz
+    format_type = "ma"  # Default MA (magnitude/angle)
+    z0 = 50.0
+
+    if option_line:
+        option_line = option_line.lower()
+        parts = option_line.split()
+
+        for i, part in enumerate(parts):
+            if part in ("hz", "khz", "mhz", "ghz"):
+                freq_unit = {
+                    "hz": 1.0,
+                    "khz": 1e3,
+                    "mhz": 1e6,
+                    "ghz": 1e9,
+                }[part]
+            elif part in ("db", "ma", "ri"):
+                format_type = part
+            elif part == "r":
+                # Reference impedance follows
+                if i + 1 < len(parts):
+                    with contextlib.suppress(ValueError):
+                        z0 = float(parts[i + 1])
+
+    # Parse data
+    frequencies = []
+    s_data = []
+
+    # Number of S-parameters per frequency
+    n_s_params = n_ports * n_ports
+
+    i = 0
+    while i < len(data_lines):
+        # First line has frequency and first S-parameters
+        parts = data_lines[i].split()
+
+        if len(parts) < 1:
+            i += 1
+            continue
+
+        freq = float(parts[0]) * freq_unit
+        frequencies.append(freq)
+
+        # Collect all S-parameter values for this frequency
+        s_values = []
+
+        # Add values from first line
+        for j in range(1, len(parts), 2):
+            if j + 1 < len(parts):
+                val1 = float(parts[j])
+                val2 = float(parts[j + 1])
+                s_values.append((val1, val2))
+
+        i += 1
+
+        # Continue collecting from subsequent lines if needed
+        while len(s_values) < n_s_params and i < len(data_lines):
+            parts = data_lines[i].split()
+
+            # Check if this is a new frequency (has odd number of values)
+            try:
+                float(parts[0])
+                if len(parts) % 2 == 1:
+                    break  # New frequency line
+            except (ValueError, IndexError):
+                pass  # Skip lines that can't be parsed as numeric data
+
+            for j in range(0, len(parts), 2):
+                if j + 1 < len(parts):
+                    val1 = float(parts[j])
+                    val2 = float(parts[j + 1])
+                    s_values.append((val1, val2))
+
+            i += 1
+
+        # Convert to complex based on format
+        s_complex = []
+        for val1, val2 in s_values:
+            if format_type == "ri":
+                # Real/Imaginary
+                s_complex.append(complex(val1, val2))
+            elif format_type == "ma":
+                # Magnitude/Angle (degrees)
+                mag = val1
+                angle_rad = np.radians(val2)
+                s_complex.append(mag * np.exp(1j * angle_rad))
+            elif format_type == "db":
+                # dB/Angle (degrees)
+                mag = 10 ** (val1 / 20)
+                angle_rad = np.radians(val2)
+                s_complex.append(mag * np.exp(1j * angle_rad))
+
+        # Reshape into matrix
+        if len(s_complex) == n_s_params:
+            s_matrix = np.array(s_complex).reshape(n_ports, n_ports)
+            s_data.append(s_matrix)
+
+    if len(frequencies) == 0:
+        raise FormatError("No valid frequency points found")
+
+    frequencies_arr = np.array(frequencies, dtype=np.float64)
+    s_matrix_arr = np.array(s_data, dtype=np.complex128)
+
+    return SParameterData(
+        frequencies=frequencies_arr,
+        s_matrix=s_matrix_arr,
+        n_ports=n_ports,
+        z0=z0,
+        format=format_type,
+        source_file=source_file,
+        comments=comments,
+    )
+
+
+__all__ = ["load_touchstone"]

oscura/math/arithmetic.py

@@ -14,8 +14,6 @@ References:
     IEEE 181-2011: Standard for Transitional Waveform Definitions
 """
 
-from __future__ import annotations
-
 import ast
 import operator
 from collections.abc import Callable

oscura/optimization/parallel.py

@@ -14,12 +14,15 @@ from concurrent.futures import (
     as_completed,
 )
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 import numpy as np
 
 from oscura.core.exceptions import AnalysisError
 
+T = TypeVar("T")
+R = TypeVar("R")
+
 if TYPE_CHECKING:
     from collections.abc import Iterable
 
@@ -29,7 +32,7 @@ logger = logging.getLogger(__name__)
 
 
 @dataclass
-class ParallelResult[R]:
+class ParallelResult(Generic[R]):
     """Result from parallel execution.
 
     Attributes:
@@ -93,7 +96,7 @@ def get_optimal_workers(max_workers: int | None = None) -> int:
     return min(max_workers, cpu_count)
 
 
-def parallel_map[T, R](
+def parallel_map(
     func: Callable[[T], R],
     iterable: Iterable[T],
     *,
@@ -171,7 +174,7 @@ def parallel_map[T, R](
     )
 
 
-def parallel_reduce[T, R](
+def parallel_reduce(
     func: Callable[[T], R],
     iterable: Iterable[T],
     reducer: Callable[[list[R]], Any],
@@ -219,7 +222,7 @@ def parallel_reduce[T, R](
     return reducer(result.results)
 
 
-def batch_parallel_map[T, R](
+def batch_parallel_map(
     func: Callable[[list[T]], list[R]],
     iterable: Iterable[T],
     *,
@@ -297,7 +300,7 @@ def batch_parallel_map[T, R](
     )
 
 
-def parallel_filter[T](
+def parallel_filter(
     func: Callable[[T], bool],
     iterable: Iterable[T],
     *,

oscura/pipeline/composition.py

@@ -4,8 +4,6 @@ This module implements compose() and pipe() functions for functional-style
 trace processing, with support for operator overloading.
 """
 
-from __future__ import annotations
-
 from collections.abc import Callable
 from functools import reduce, wraps
 from typing import Any, TypeVar

oscura/plugins/cli.py

@@ -4,8 +4,6 @@ This module provides command-line interface for plugin management including
 list, info, enable/disable, install, and validate operations.
 """
 
-from __future__ import annotations
-
 import hashlib
 import logging
 import shutil