oscura 0.8.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

oscura/sessions/legacy.py

@@ -17,6 +17,7 @@ import gzip
 import hashlib
 import hmac
 import pickle
+import secrets
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
@@ -28,7 +29,45 @@ from oscura.core.exceptions import SecurityError
 # Session file format constants
 _SESSION_MAGIC = b"OSC1"  # Magic bytes for new format with signature
 _SESSION_SIGNATURE_SIZE = 32  # SHA256 hash size in bytes
-_SECURITY_KEY = hashlib.sha256(b"oscura-session-v1").digest()
+
+
+def _get_security_key() -> bytes:
+    """Get or generate per-installation session security key.
+
+    The key is generated once per installation and stored in ~/.oscura/session_key
+    with restrictive permissions (0o600). This provides better security than a
+    shared hardcoded key.
+
+    Returns:
+        32-byte security key for HMAC signing.
+    """
+    key_file = Path.home() / ".oscura" / "session_key"
+
+    if key_file.exists():
+        # Load existing key
+        try:
+            return key_file.read_bytes()
+        except (OSError, PermissionError):
+            # Fall back to generating new key if can't read
+            pass
+
+    # Generate new random key
+    key_file.parent.mkdir(parents=True, exist_ok=True)
+    key = secrets.token_bytes(32)
+
+    # Write with restrictive permissions
+    try:
+        key_file.write_bytes(key)
+        key_file.chmod(0o600)  # Owner read/write only
+    except (OSError, PermissionError):
+        # Can't write key file - continue with ephemeral key
+        # This happens in read-only filesystems or restricted environments
+        pass
+
+    return key
+
+
+_SECURITY_KEY = _get_security_key()
 
 
 class AnnotationType(Enum):
@@ -709,6 +748,15 @@ class Session:
 def load_session(path: str | Path) -> Session:
     """Load session from file.
 
+    This function implements HMAC-SHA256 signature verification before deserializing
+    session data to protect against tampering and malicious file modifications.
+
+    Security:
+        Session files are protected with HMAC-SHA256 signatures. Only load session
+        files from trusted sources. While HMAC verification prevents tampering,
+        the shared security key means all installations can verify each other's
+        files. Consider using per-installation keys for sensitive deployments.
+
     Args:
         path: Path to session file (.tks).
 

oscura/side_channel/__init__.py

@@ -1,63 +1,44 @@
-"""Side-channel analysis for cryptographic implementation attacks.
-
-.. deprecated:: 0.6.0
-    This module is deprecated. Use :mod:`oscura.analyzers.side_channel` instead.
-    This module will be removed in v1.0.0.
-
-This package provides tools for performing side-channel attacks on cryptographic
-implementations using power analysis, electromagnetic analysis, timing analysis,
-and fault injection techniques.
-
-Migration Guide:
-    Old import (deprecated):
-        >>> from oscura.side_channel.dpa import DPAAnalyzer, PowerTrace
-
-    New import (recommended):
-        >>> from oscura.analyzers.side_channel import DPAAnalyzer, CPAAnalyzer
-        >>> from oscura.analyzers.side_channel.power import hamming_weight
-
-Note:
-    The oscura.side_channel.dpa module contains a different DPAAnalyzer implementation
-    than oscura.analyzers.side_channel.power. The older implementation in this module
-    (oscura.side_channel.dpa.DPAAnalyzer) supports combined DPA/CPA/Template attacks
-    with a single class. The newer implementation in oscura.analyzers.side_channel
-    provides separate DPAAnalyzer and CPAAnalyzer classes with cleaner APIs.
-
-    For new code, use the oscura.analyzers.side_channel module.
-    For existing code using DPAAnalyzer with attack_type parameter, continue using
-    oscura.side_channel.dpa until migration to the new API.
-
-Example (new API - recommended):
-    >>> from oscura.analyzers.side_channel import DPAAnalyzer, CPAAnalyzer
-    >>> # DPA attack
-    >>> dpa = DPAAnalyzer(target_bit=0)
-    >>> result = dpa.analyze(traces, plaintexts)
-    >>> # CPA attack
-    >>> cpa = CPAAnalyzer(leakage_model="hamming_weight")
-    >>> result = cpa.analyze(traces, plaintexts)
-
-Example (old API - deprecated):
-    >>> from oscura.side_channel.dpa import DPAAnalyzer, PowerTrace
-    >>> analyzer = DPAAnalyzer(attack_type="cpa", leakage_model="hamming_weight")
-    >>> traces = [PowerTrace(timestamp=t, power=p, plaintext=pt) for ...]
-    >>> result = analyzer.perform_attack(traces, target_byte=0)
+"""Side-channel trace loading.
+
+This module ONLY provides ChipWhisperer trace loading for integration
+into Oscura workflows.
+
+For actual side-channel attacks, use ChipWhisperer directly:
+https://chipwhisperer.com/
+
+What's here:
+- ChipWhisperer .npy/.trs trace loading via oscura.loaders.chipwhisperer
+
+What's NOT here (use ChipWhisperer instead):
+- DPA/CPA attacks
+- Key recovery
+- Leakage assessment
+- Template attacks
+- Hardware interfacing
+
+Example:
+    >>> from oscura.loaders.chipwhisperer import load_chipwhisperer
+    >>> traceset = load_chipwhisperer("capture_data.npy")
+    >>> print(f"Loaded {traceset.n_traces} traces")
+
+References:
+    ChipWhisperer Project: https://chipwhisperer.com/
+    ChipWhisperer Documentation: https://chipwhisperer.readthedocs.io/
 """
 
 from __future__ import annotations
 
-import warnings
-
-# Issue deprecation warning on import
-warnings.warn(
-    "oscura.side_channel is deprecated and will be removed in v1.0.0. "
-    "Use oscura.analyzers.side_channel instead. "
-    "See migration guide in module docstring.",
-    DeprecationWarning,
-    stacklevel=2,
+# Re-export ChipWhisperer loader for convenience
+from oscura.loaders.chipwhisperer import (
+    ChipWhispererTraceSet,
+    load_chipwhisperer,
+    load_chipwhisperer_npy,
+    load_chipwhisperer_trs,
 )
 
-# Re-export from the local dpa module for backward compatibility
-# The dpa.py module in this directory contains the legacy implementation
-from oscura.side_channel.dpa import DPAAnalyzer, DPAResult, PowerTrace
-
-__all__ = ["DPAAnalyzer", "DPAResult", "PowerTrace"]
+__all__ = [
+    "ChipWhispererTraceSet",
+    "load_chipwhisperer",
+    "load_chipwhisperer_npy",
+    "load_chipwhisperer_trs",
+]

oscura/utils/builders/signal_builder.py

@@ -940,7 +940,7 @@ class SignalBuilder:
         # Build TraceMetadata
         trace_metadata = TraceMetadata(
             sample_rate=self._sample_rate,
-            channel_name=channel,
+            channel=channel,
         )
 
         return WaveformTrace(data=data, metadata=trace_metadata)
@@ -977,12 +977,12 @@ class SignalBuilder:
 
         # Build WaveformTrace for each channel
         traces: dict[str, WaveformTrace] = {}
-        for channel_name, data in self._channels.items():
+        for channel, data in self._channels.items():
             trace_metadata = TraceMetadata(
                 sample_rate=self._sample_rate,
-                channel_name=channel_name,
+                channel=channel,
             )
-            traces[channel_name] = WaveformTrace(data=data, metadata=trace_metadata)
+            traces[channel] = WaveformTrace(data=data, metadata=trace_metadata)
 
         return traces
 
@@ -1010,7 +1010,7 @@ class SignalBuilder:
             path,
             data=trace.data,
             sample_rate=trace.metadata.sample_rate,
-            channel_name=trace.metadata.channel_name or "ch1",
+            channel=trace.metadata.channel or "ch1",
         )
 
         return trace

oscura/utils/comparison/compare.py

@@ -59,7 +59,7 @@ def difference(
     trace2: WaveformTrace,
     *,
     normalize: bool = False,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Compute difference between two traces.
 
@@ -70,7 +70,7 @@ def difference(
         trace1: First trace.
         trace2: Second trace.
         normalize: Normalize difference to percentage of reference range.
-        channel_name: Name for the result trace.
+        channel: Name for the result trace.
 
     Returns:
         WaveformTrace containing the difference.
@@ -106,12 +106,10 @@ def difference(
 
     new_metadata = TraceMetadata(
         sample_rate=trace1.metadata.sample_rate,
-        vertical_scale=None,
-        vertical_offset=None,
-        acquisition_time=trace1.metadata.acquisition_time,
-        trigger_info=trace1.metadata.trigger_info,
-        source_file=trace1.metadata.source_file,
-        channel_name=channel_name or "difference",
+        vertical_scale=trace1.metadata.vertical_scale,
+        vertical_offset=trace1.metadata.vertical_offset,
+        channel=channel or "difference",
+        units=trace1.metadata.units,
     )
 
     return WaveformTrace(data=diff, metadata=new_metadata)
@@ -482,7 +480,7 @@ def compare_traces(
     match = _determine_match(method, max_diff, tolerance, tolerance_pct, data1, data2)
 
     diff_trace = (
-        difference(trace1, trace2, channel_name="comparison_diff") if include_difference else None
+        difference(trace1, trace2, channel="comparison_diff") if include_difference else None
     )
     statistics = _compute_comparison_statistics(diff, violations, min_len, data1, data2)
 

oscura/utils/comparison/golden.py

@@ -235,7 +235,7 @@ def create_golden(
         description=description,
         metadata={
             "source_file": trace.metadata.source_file,
-            "channel_name": trace.metadata.channel_name,
+            "channel": trace.metadata.channel,
         },
     )
 

oscura/utils/filtering/convenience.py

@@ -496,7 +496,7 @@ def differentiate(
     if order < 1:
         raise AnalysisError(f"Derivative order must be positive, got {order}")
 
-    sample_period = trace.metadata.time_base
+    sample_period = 1.0 / trace.metadata.sample_rate
     result = trace.data.copy()
 
     for _ in range(order):
@@ -530,7 +530,7 @@ def integrate(
     Example:
         >>> position = integrate(velocity_trace)
     """
-    sample_period = trace.metadata.time_base
+    sample_period = 1.0 / trace.metadata.sample_rate
 
     if method == "cumtrapz":
         from scipy.integrate import cumulative_trapezoid

oscura/utils/math/arithmetic.py

@@ -73,7 +73,7 @@ def add(
     trace1: WaveformTrace,
     trace2: TraceOrScalar,
     *,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Add two traces or add a scalar to a trace.
 
@@ -83,7 +83,7 @@ def add(
     Args:
         trace1: First trace (base trace).
         trace2: Second trace or scalar value to add.
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         New WaveformTrace containing the sum.
@@ -121,10 +121,7 @@ def add(
         sample_rate=metadata.sample_rate,
         vertical_scale=metadata.vertical_scale,
         vertical_offset=metadata.vertical_offset,
-        acquisition_time=metadata.acquisition_time,
-        trigger_info=metadata.trigger_info,
-        source_file=metadata.source_file,
-        channel_name=channel_name or f"{metadata.channel_name or 'trace'}_sum",
+        channel=channel or f"{metadata.channel or 'trace'}_sum",
     )
 
     return WaveformTrace(data=result_data, metadata=new_metadata)
@@ -134,7 +131,7 @@ def subtract(
     trace1: WaveformTrace,
     trace2: TraceOrScalar,
     *,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Subtract second trace from first trace or subtract a scalar.
 
@@ -144,7 +141,7 @@ def subtract(
     Args:
         trace1: Trace to subtract from.
         trace2: Trace or scalar to subtract.
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         New WaveformTrace containing the difference.
@@ -178,10 +175,7 @@ def subtract(
         sample_rate=metadata.sample_rate,
         vertical_scale=metadata.vertical_scale,
         vertical_offset=metadata.vertical_offset,
-        acquisition_time=metadata.acquisition_time,
-        trigger_info=metadata.trigger_info,
-        source_file=metadata.source_file,
-        channel_name=channel_name or f"{metadata.channel_name or 'trace'}_diff",
+        channel=channel or f"{metadata.channel or 'trace'}_diff",
     )
 
     return WaveformTrace(data=result_data, metadata=new_metadata)
@@ -191,7 +185,7 @@ def multiply(
     trace1: WaveformTrace,
     trace2: TraceOrScalar,
     *,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Multiply two traces or multiply trace by a scalar.
 
@@ -201,7 +195,7 @@ def multiply(
     Args:
         trace1: First trace.
         trace2: Second trace or scalar multiplier.
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         New WaveformTrace containing the product.
@@ -235,10 +229,7 @@ def multiply(
         sample_rate=metadata.sample_rate,
         vertical_scale=metadata.vertical_scale,
         vertical_offset=metadata.vertical_offset,
-        acquisition_time=metadata.acquisition_time,
-        trigger_info=metadata.trigger_info,
-        source_file=metadata.source_file,
-        channel_name=channel_name or f"{metadata.channel_name or 'trace'}_mult",
+        channel=channel or f"{metadata.channel or 'trace'}_mult",
     )
 
     return WaveformTrace(data=result_data, metadata=new_metadata)
@@ -248,7 +239,7 @@ def divide(
     trace1: WaveformTrace,
     trace2: TraceOrScalar,
     *,
-    channel_name: str | None = None,
+    channel: str | None = None,
     fill_value: float = np.nan,
 ) -> WaveformTrace:
     """Divide first trace by second trace or by a scalar.
@@ -259,7 +250,7 @@ def divide(
     Args:
         trace1: Numerator trace.
         trace2: Denominator trace or scalar.
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
         fill_value: Value to use for division by zero (default NaN).
 
     Returns:
@@ -301,10 +292,7 @@ def divide(
         sample_rate=metadata.sample_rate,
         vertical_scale=metadata.vertical_scale,
         vertical_offset=metadata.vertical_offset,
-        acquisition_time=metadata.acquisition_time,
-        trigger_info=metadata.trigger_info,
-        source_file=metadata.source_file,
-        channel_name=channel_name or f"{metadata.channel_name or 'trace'}_div",
+        channel=channel or f"{metadata.channel or 'trace'}_div",
     )
 
     return WaveformTrace(data=result_data, metadata=new_metadata)
@@ -314,7 +302,7 @@ def scale(
     trace: WaveformTrace,
     factor: float,
     *,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Scale trace by a constant factor.
 
@@ -324,7 +312,7 @@ def scale(
     Args:
         trace: Input trace.
         factor: Scale factor to apply.
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         Scaled WaveformTrace.
@@ -336,7 +324,7 @@ def scale(
     return multiply(
         trace,
         factor,
-        channel_name=channel_name or f"{trace.metadata.channel_name or 'trace'}_scaled",
+        channel=channel or f"{trace.metadata.channel or 'trace'}_scaled",
     )
 
 
@@ -344,7 +332,7 @@ def offset(
     trace: WaveformTrace,
     value: float,
     *,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Add a constant offset to trace.
 
@@ -353,7 +341,7 @@ def offset(
     Args:
         trace: Input trace.
         value: Offset value to add.
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         Offset WaveformTrace.
@@ -364,14 +352,14 @@ def offset(
     return add(
         trace,
         value,
-        channel_name=channel_name or f"{trace.metadata.channel_name or 'trace'}_offset",
+        channel=channel or f"{trace.metadata.channel or 'trace'}_offset",
     )
 
 
 def invert(
     trace: WaveformTrace,
     *,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Invert trace polarity (multiply by -1).
 
@@ -379,7 +367,7 @@ def invert(
 
     Args:
         trace: Input trace.
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         Inverted WaveformTrace.
@@ -390,14 +378,14 @@ def invert(
     return scale(
         trace,
         -1.0,
-        channel_name=channel_name or f"{trace.metadata.channel_name or 'trace'}_inverted",
+        channel=channel or f"{trace.metadata.channel or 'trace'}_inverted",
     )
 
 
 def absolute(
     trace: WaveformTrace,
     *,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Compute absolute value of trace.
 
@@ -405,7 +393,7 @@ def absolute(
 
     Args:
         trace: Input trace.
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         WaveformTrace with absolute values.
@@ -419,10 +407,7 @@ def absolute(
         sample_rate=trace.metadata.sample_rate,
         vertical_scale=trace.metadata.vertical_scale,
         vertical_offset=trace.metadata.vertical_offset,
-        acquisition_time=trace.metadata.acquisition_time,
-        trigger_info=trace.metadata.trigger_info,
-        source_file=trace.metadata.source_file,
-        channel_name=channel_name or f"{trace.metadata.channel_name or 'trace'}_abs",
+        channel=channel or f"{trace.metadata.channel or 'trace'}_abs",
     )
 
     return WaveformTrace(data=result_data, metadata=new_metadata)
@@ -433,7 +418,7 @@ def differentiate(
     *,
     order: int = 1,
     method: str = "central",
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Compute numerical derivative of trace.
 
@@ -447,7 +432,7 @@ def differentiate(
             - "central": Central difference (default, most accurate)
             - "forward": Forward difference
             - "backward": Backward difference
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         Differentiated WaveformTrace in V/s.
@@ -467,7 +452,7 @@ def differentiate(
         raise ValueError(f"Order must be positive, got {order}")
 
     data = trace.data.astype(np.float64)
-    dt = trace.metadata.time_base
+    dt = 1.0 / trace.metadata.sample_rate
 
     if len(data) < order + 1:
         raise InsufficientDataError(
@@ -500,10 +485,7 @@ def differentiate(
         sample_rate=trace.metadata.sample_rate,
         vertical_scale=None,  # Units changed
         vertical_offset=None,
-        acquisition_time=trace.metadata.acquisition_time,
-        trigger_info=trace.metadata.trigger_info,
-        source_file=trace.metadata.source_file,
-        channel_name=channel_name or f"{trace.metadata.channel_name or 'trace'}_d{order}",
+        channel=channel or f"{trace.metadata.channel or 'trace'}_d{order}",
     )
 
     return WaveformTrace(data=result, metadata=new_metadata)
@@ -514,7 +496,7 @@ def integrate(
     *,
     method: str = "trapezoid",
     initial: float = 0.0,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Compute numerical integral of trace.
 
@@ -528,7 +510,7 @@ def integrate(
             - "simpson": Simpson's rule (requires odd number of points)
             - "cumsum": Simple cumulative sum
         initial: Initial value for cumulative integral (default 0).
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         Integrated WaveformTrace in V*s.
@@ -545,7 +527,7 @@ def integrate(
         ARITH-006
     """
     data = trace.data.astype(np.float64)
-    dt = trace.metadata.time_base
+    dt = 1.0 / trace.metadata.sample_rate
 
     if len(data) < 2:
         raise InsufficientDataError(
@@ -572,10 +554,7 @@ def integrate(
         sample_rate=trace.metadata.sample_rate,
         vertical_scale=None,  # Units changed
         vertical_offset=None,
-        acquisition_time=trace.metadata.acquisition_time,
-        trigger_info=trace.metadata.trigger_info,
-        source_file=trace.metadata.source_file,
-        channel_name=channel_name or f"{trace.metadata.channel_name or 'trace'}_integral",
+        channel=channel or f"{trace.metadata.channel or 'trace'}_integral",
     )
 
     return WaveformTrace(data=result, metadata=new_metadata)
@@ -818,14 +797,14 @@ def _ensure_array_result(result: Any, expected_len: int) -> NDArray[np.float64]:
 
 
 def _build_expression_metadata(
-    ref_trace: WaveformTrace, expression: str, channel_name: str | None
+    ref_trace: WaveformTrace, expression: str, channel: str | None
 ) -> TraceMetadata:
     """Build metadata for expression result trace.
 
     Args:
         ref_trace: Reference trace for metadata.
         expression: Expression string (for default naming).
-        channel_name: Optional channel name override.
+        channel: Optional channel name override.
 
     Returns:
         Metadata for result trace.
@@ -834,10 +813,7 @@ def _build_expression_metadata(
         sample_rate=ref_trace.metadata.sample_rate,
         vertical_scale=None,
         vertical_offset=None,
-        acquisition_time=ref_trace.metadata.acquisition_time,
-        trigger_info=ref_trace.metadata.trigger_info,
-        source_file=ref_trace.metadata.source_file,
-        channel_name=channel_name or f"expr({expression[:20]})",
+        channel=channel or f"expr({expression[:20]})",
     )
 
 
@@ -845,7 +821,7 @@ def math_expression(
     expression: str,
     traces: dict[str, WaveformTrace],
     *,
-    channel_name: str | None = None,
+    channel: str | None = None,
 ) -> WaveformTrace:
     """Evaluate a mathematical expression on traces.
 
@@ -855,7 +831,7 @@ def math_expression(
     Args:
         expression: Math expression (e.g., "CH1 + CH2", "abs(CH1 - CH2)").
         traces: Dictionary mapping variable names to traces.
-        channel_name: Name for the result trace (optional).
+        channel: Name for the result trace (optional).
 
     Returns:
         Result WaveformTrace.
@@ -884,5 +860,5 @@ def math_expression(
     result = _evaluate_expression(expression, safe_namespace)
     result = _ensure_array_result(result, len(ref_trace.data))
 
-    metadata = _build_expression_metadata(ref_trace, expression, channel_name)
+    metadata = _build_expression_metadata(ref_trace, expression, channel)
     return WaveformTrace(data=result.astype(np.float64), metadata=metadata)