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

oscura/analyzers/protocols/parallel_bus.py

@@ -0,0 +1,449 @@
+"""Parallel bus protocol decoders for vintage systems.
+
+Implements decoders for classic parallel bus protocols:
+- IEEE-488 (GPIB): General Purpose Interface Bus for instruments
+- Centronics: Parallel printer interface
+- ISA: Industry Standard Architecture bus
+
+Example:
+    >>> from oscura.analyzers.protocols.parallel_bus import decode_gpib, decode_centronics
+    >>> frames = decode_gpib(dio_lines, dav, nrfd, ndac, eoi, atn)
+    >>> print_data = decode_centronics(data_lines, strobe, busy, ack)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+# =============================================================================
+# IEEE-488 (GPIB) Protocol Decoder
+# =============================================================================
+
+
+class GPIBMessageType(Enum):
+    """GPIB message types."""
+
+    DATA = "data"  # Data bytes (ATN=0)
+    COMMAND = "command"  # Command bytes (ATN=1)
+    TALK_ADDRESS = "talk_address"  # Talk address
+    LISTEN_ADDRESS = "listen_address"  # Listen address
+    SECONDARY_ADDRESS = "secondary_address"  # Secondary address
+    UNIVERSAL_COMMAND = "universal_command"  # Universal command
+    ADDRESSED_COMMAND = "addressed_command"  # Addressed command
+
+
+@dataclass
+class GPIBFrame:
+    """A decoded GPIB frame.
+
+    Attributes:
+        timestamp: Frame timestamp in seconds.
+        data: Data byte value (0-255).
+        message_type: Type of GPIB message.
+        eoi: End-Or-Identify asserted.
+        description: Human-readable description.
+    """
+
+    timestamp: float
+    data: int
+    message_type: GPIBMessageType
+    eoi: bool
+    description: str
+
+
+def decode_gpib(
+    dio_lines: list[NDArray[np.bool_]],  # DIO1-DIO8 (8 data lines)
+    dav: NDArray[np.bool_],  # Data Valid
+    nrfd: NDArray[np.bool_],  # Not Ready For Data
+    ndac: NDArray[np.bool_],  # Not Data Accepted
+    eoi: NDArray[np.bool_],  # End Or Identify
+    atn: NDArray[np.bool_],  # Attention
+    sample_rate: float = 1.0,
+) -> list[GPIBFrame]:
+    """Decode IEEE-488 (GPIB) bus transactions.
+
+    Args:
+        dio_lines: List of 8 digital traces for DIO1-DIO8.
+        dav: Data Valid signal (active low).
+        nrfd: Not Ready For Data signal (active low).
+        ndac: Not Data Accepted signal (active low).
+        eoi: End Or Identify signal (active low).
+        atn: Attention signal (active low).
+        sample_rate: Sample rate in Hz.
+
+    Returns:
+        List of GPIBFrame objects.
+
+    Example:
+        >>> frames = decode_gpib(dio, dav, nrfd, ndac, eoi, atn, 1e6)
+        >>> for frame in frames:
+        ...     print(f"{frame.timestamp*1e6:.1f}us: {frame.description}")
+    """
+    if len(dio_lines) != 8:
+        raise ValueError("GPIB requires exactly 8 DIO lines")
+
+    frames: list[GPIBFrame] = []
+    time_base = 1.0 / sample_rate
+
+    # Combine DIO lines into data bus
+    data_bus = np.zeros(len(dio_lines[0]), dtype=np.uint8)
+    for i, line in enumerate(dio_lines):
+        data_bus |= (line.astype(np.uint8) << i).astype(np.uint8)
+
+    # Detect DAV falling edges (data valid)
+    dav_falling = np.where(np.diff(dav.astype(np.int8)) == -1)[0]
+
+    for idx in dav_falling:
+        # Sample data after falling edge
+        sample_idx = idx + 1
+        if sample_idx >= len(data_bus):
+            continue
+
+        timestamp = idx * time_base
+        data_byte = int(data_bus[sample_idx])
+        eoi_active = not eoi[sample_idx]  # Active low
+        atn_active = not atn[sample_idx]  # Active low
+
+        # Decode message type based on ATN and data
+        if atn_active:
+            # Check address bytes first (bit patterns for talk/listen)
+            if data_byte & 0x40:
+                # Talk address (bit 6 set)
+                address = data_byte & 0x1F
+                msg_type = GPIBMessageType.TALK_ADDRESS
+                desc = f"Talk address {address}"
+            elif data_byte & 0x20:
+                # Listen address (bit 5 set, bit 6 clear)
+                address = data_byte & 0x1F
+                msg_type = GPIBMessageType.LISTEN_ADDRESS
+                desc = f"Listen address {address}"
+            elif 0x10 <= data_byte <= 0x1F:
+                # Universal commands
+                msg_type = GPIBMessageType.UNIVERSAL_COMMAND
+                desc = _gpib_universal_command_name(data_byte)
+            else:
+                # Addressed commands (0x00-0x0F and others)
+                msg_type = GPIBMessageType.ADDRESSED_COMMAND
+                desc = _gpib_addressed_command_name(data_byte)
+        else:
+            # Data byte
+            msg_type = GPIBMessageType.DATA
+            desc = f"Data: 0x{data_byte:02X}"
+            if 32 <= data_byte <= 126:
+                desc += f" ('{chr(data_byte)}')"
+
+        if eoi_active:
+            desc += " [EOI]"
+
+        frames.append(
+            GPIBFrame(
+                timestamp=timestamp,
+                data=data_byte,
+                message_type=msg_type,
+                eoi=eoi_active,
+                description=desc,
+            )
+        )
+
+    return frames
+
+
+def _gpib_universal_command_name(cmd: int) -> str:
+    """Get name of GPIB universal command."""
+    commands = {
+        0x11: "DCL (Device Clear)",
+        0x14: "GET (Group Execute Trigger)",
+        0x15: "GTL (Go To Local)",
+        0x08: "LLO (Local Lockout)",
+        0x01: "SPD (Serial Poll Disable)",
+        0x18: "SPE (Serial Poll Enable)",
+        0x13: "PPU (Parallel Poll Unconfigure)",
+    }
+    return commands.get(cmd, f"Unknown universal command 0x{cmd:02X}")
+
+
+def _gpib_addressed_command_name(cmd: int) -> str:
+    """Get name of GPIB addressed command."""
+    commands = {
+        0x04: "SDC (Selected Device Clear)",
+        0x05: "PPC (Parallel Poll Configure)",
+        0x09: "TCT (Take Control)",
+    }
+    return commands.get(cmd, f"Unknown addressed command 0x{cmd:02X}")
+
+
+# =============================================================================
+# Centronics Parallel Printer Protocol Decoder
+# =============================================================================
+
+
+@dataclass
+class CentronicsFrame:
+    """A decoded Centronics printer frame.
+
+    Attributes:
+        timestamp: Frame timestamp in seconds.
+        data: Data byte value (0-255).
+        character: ASCII character (if printable).
+        control: Control signal states.
+    """
+
+    timestamp: float
+    data: int
+    character: str | None
+    control: dict[str, bool]
+
+
+def decode_centronics(
+    data_lines: list[NDArray[np.bool_]],  # D0-D7 (8 data lines)
+    strobe: NDArray[np.bool_],  # Strobe signal (active low)
+    busy: NDArray[np.bool_],  # Busy signal
+    ack: NDArray[np.bool_],  # Acknowledge signal (active low)
+    sample_rate: float = 1.0,
+    *,
+    select: NDArray[np.bool_] | None = None,  # Select signal
+    paper_out: NDArray[np.bool_] | None = None,  # Paper Out signal
+    error: NDArray[np.bool_] | None = None,  # Error signal
+) -> list[CentronicsFrame]:
+    """Decode Centronics parallel printer protocol.
+
+    Args:
+        data_lines: List of 8 digital traces for D0-D7.
+        strobe: Strobe signal (active low).
+        busy: Busy signal (high when printer busy).
+        ack: Acknowledge signal (active low pulse).
+        sample_rate: Sample rate in Hz.
+        select: Optional select signal.
+        paper_out: Optional paper out signal.
+        error: Optional error signal.
+
+    Returns:
+        List of CentronicsFrame objects.
+
+    Example:
+        >>> frames = decode_centronics(data, strobe, busy, ack, 1e6)
+        >>> for frame in frames:
+        ...     if frame.character:
+        ...         print(frame.character, end='')
+    """
+    if len(data_lines) != 8:
+        raise ValueError("Centronics requires exactly 8 data lines")
+
+    frames: list[CentronicsFrame] = []
+    time_base = 1.0 / sample_rate
+
+    # Combine data lines into bytes
+    data_bus = np.zeros(len(data_lines[0]), dtype=np.uint8)
+    for i, line in enumerate(data_lines):
+        data_bus |= (line.astype(np.uint8) << i).astype(np.uint8)
+
+    # Detect STROBE falling edges (data latch)
+    strobe_falling = np.where(np.diff(strobe.astype(np.int8)) == -1)[0]
+
+    for idx in strobe_falling:
+        # Sample data after falling edge
+        sample_idx = idx + 1
+        if sample_idx >= len(data_bus):
+            continue
+
+        timestamp = idx * time_base
+        data_byte = int(data_bus[sample_idx])
+
+        # Check if printable ASCII
+        char = chr(data_byte) if 32 <= data_byte <= 126 else None
+
+        # Capture control signals
+        control = {
+            "busy": bool(busy[sample_idx]),
+            "ack": not ack[sample_idx],  # Active low
+        }
+
+        if select is not None:
+            control["select"] = bool(select[sample_idx])
+        if paper_out is not None:
+            control["paper_out"] = bool(paper_out[sample_idx])
+        if error is not None:
+            control["error"] = bool(error[sample_idx])
+
+        frames.append(
+            CentronicsFrame(
+                timestamp=timestamp,
+                data=data_byte,
+                character=char,
+                control=control,
+            )
+        )
+
+    return frames
+
+
+# =============================================================================
+# ISA Bus Protocol Analyzer
+# =============================================================================
+
+
+class ISACycleType(Enum):
+    """ISA bus cycle types."""
+
+    MEMORY_READ = "memory_read"
+    MEMORY_WRITE = "memory_write"
+    IO_READ = "io_read"
+    IO_WRITE = "io_write"
+    DMA = "dma"
+    INTERRUPT = "interrupt"
+
+
+@dataclass
+class ISATransaction:
+    """An ISA bus transaction.
+
+    Attributes:
+        timestamp: Transaction timestamp in seconds.
+        cycle_type: Type of bus cycle.
+        address: Address (20-bit for memory, 16-bit for I/O).
+        data: Data byte (if applicable).
+        description: Human-readable description.
+    """
+
+    timestamp: float
+    cycle_type: ISACycleType
+    address: int
+    data: int | None
+    description: str
+
+
+def decode_isa_bus(
+    address_lines: list[NDArray[np.bool_]],  # SA0-SA19 (20 address lines)
+    data_lines: list[NDArray[np.bool_]],  # SD0-SD7 (8 data lines)
+    ior: NDArray[np.bool_],  # I/O Read (active low)
+    iow: NDArray[np.bool_],  # I/O Write (active low)
+    memr: NDArray[np.bool_],  # Memory Read (active low)
+    memw: NDArray[np.bool_],  # Memory Write (active low)
+    ale: NDArray[np.bool_],  # Address Latch Enable
+    sample_rate: float = 1.0,
+) -> list[ISATransaction]:
+    """Decode ISA bus transactions.
+
+    Args:
+        address_lines: List of 20 digital traces for SA0-SA19.
+        data_lines: List of 8 digital traces for SD0-SD7.
+        ior: I/O Read signal (active low).
+        iow: I/O Write signal (active low).
+        memr: Memory Read signal (active low).
+        memw: Memory Write signal (active low).
+        ale: Address Latch Enable.
+        sample_rate: Sample rate in Hz.
+
+    Returns:
+        List of ISATransaction objects.
+
+    Example:
+        >>> trans = decode_isa_bus(addr, data, ior, iow, memr, memw, ale, 1e6)
+        >>> for t in trans:
+        ...     print(f"{t.timestamp*1e6:.1f}us: {t.description}")
+    """
+    if len(address_lines) < 16:
+        raise ValueError("ISA bus requires at least 16 address lines")
+    if len(data_lines) != 8:
+        raise ValueError("ISA bus requires exactly 8 data lines")
+
+    transactions: list[ISATransaction] = []
+    time_base = 1.0 / sample_rate
+
+    # Combine address lines
+    address_bus = np.zeros(len(address_lines[0]), dtype=np.uint32)
+    for i, line in enumerate(address_lines):
+        address_bus |= (line.astype(np.uint32) << i).astype(np.uint32)
+
+    # Combine data lines
+    data_bus = np.zeros(len(data_lines[0]), dtype=np.uint8)
+    for i, line in enumerate(data_lines):
+        data_bus |= (line.astype(np.uint8) << i).astype(np.uint8)
+
+    # Detect ALE falling edges (address latch)
+    ale_falling = np.where(np.diff(ale.astype(np.int8)) == -1)[0]
+
+    for idx in ale_falling:
+        if idx >= len(address_bus):
+            continue
+
+        timestamp = idx * time_base
+        address = int(address_bus[idx])
+
+        # Look ahead for read/write strobes (larger window to catch delayed strobes)
+        search_window = min(idx + 200, len(ior))
+
+        ior_active = np.any(~ior[idx:search_window])
+        iow_active = np.any(~iow[idx:search_window])
+        memr_active = np.any(~memr[idx:search_window])
+        memw_active = np.any(~memw[idx:search_window])
+
+        # Determine cycle type
+        data_val = None
+
+        if ior_active:
+            cycle_type = ISACycleType.IO_READ
+            desc = f"I/O Read from 0x{address:04X}"
+            # Find data at IOR falling edge
+            ior_idx = np.where(~ior[idx:search_window])[0]
+            if len(ior_idx) > 0:
+                data_val = int(data_bus[idx + ior_idx[0]])
+                desc += f" = 0x{data_val:02X}"
+
+        elif iow_active:
+            cycle_type = ISACycleType.IO_WRITE
+            iow_idx = np.where(~iow[idx:search_window])[0]
+            if len(iow_idx) > 0:
+                data_val = int(data_bus[idx + iow_idx[0]])
+            desc = f"I/O Write 0x{data_val:02X} to 0x{address:04X}"
+
+        elif memr_active:
+            cycle_type = ISACycleType.MEMORY_READ
+            desc = f"Memory Read from 0x{address:05X}"
+            memr_idx = np.where(~memr[idx:search_window])[0]
+            if len(memr_idx) > 0:
+                data_val = int(data_bus[idx + memr_idx[0]])
+                desc += f" = 0x{data_val:02X}"
+
+        elif memw_active:
+            cycle_type = ISACycleType.MEMORY_WRITE
+            memw_idx = np.where(~memw[idx:search_window])[0]
+            if len(memw_idx) > 0:
+                data_val = int(data_bus[idx + memw_idx[0]])
+            desc = f"Memory Write 0x{data_val:02X} to 0x{address:05X}"
+
+        else:
+            # No control signals active
+            continue
+
+        transactions.append(
+            ISATransaction(
+                timestamp=timestamp,
+                cycle_type=cycle_type,
+                address=address,
+                data=data_val,
+                description=desc,
+            )
+        )
+
+    return transactions
+
+
+__all__ = [
+    "CentronicsFrame",
+    "GPIBFrame",
+    "GPIBMessageType",
+    "ISACycleType",
+    "ISATransaction",
+    "decode_centronics",
+    "decode_gpib",
+    "decode_isa_bus",
+]

oscura/analyzers/side_channel/__init__.py

@@ -0,0 +1,52 @@
+"""Side-channel analysis module.
+
+This module provides research-grade implementations of side-channel analysis
+techniques including Differential Power Analysis (DPA), Correlation Power
+Analysis (CPA), and timing analysis.
+
+Example:
+    >>> from oscura.analyzers.side_channel import DPAAnalyzer, CPAAnalyzer
+    >>> # DPA attack
+    >>> dpa = DPAAnalyzer(target_bit=0)
+    >>> result = dpa.analyze(traces, plaintexts)
+    >>> print(f"Key byte guess: 0x{result.key_guess:02X}")
+    >>>
+    >>> # CPA attack
+    >>> cpa = CPAAnalyzer(leakage_model="hamming_weight")
+    >>> result = cpa.analyze(traces, plaintexts)
+    >>> print(f"Correlation: {result.max_correlation:.4f}")
+
+References:
+    Kocher et al. "Differential Power Analysis" (CRYPTO 1999)
+    Brier et al. "Correlation Power Analysis" (CHES 2004)
+"""
+
+from oscura.analyzers.side_channel.power import (
+    CPAAnalyzer,
+    CPAResult,
+    DPAAnalyzer,
+    DPAResult,
+    LeakageModel,
+    hamming_distance,
+    hamming_weight,
+)
+from oscura.analyzers.side_channel.timing import (
+    TimingAnalyzer,
+    TimingAttackResult,
+    TimingLeak,
+)
+
+__all__ = [
+    # Power analysis
+    "CPAAnalyzer",
+    "CPAResult",
+    "DPAAnalyzer",
+    "DPAResult",
+    "LeakageModel",
+    # Timing analysis
+    "TimingAnalyzer",
+    "TimingAttackResult",
+    "TimingLeak",
+    "hamming_distance",
+    "hamming_weight",
+]