oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/iot/coap/options.py

@@ -0,0 +1,212 @@
+"""CoAP option definitions and parsing helpers.
+
+Provides option number to name mappings, content format definitions,
+and helper functions for decoding CoAP options.
+
+References:
+    RFC 7252 Section 5.10: Option Definitions
+    RFC 7252 Section 12.3: CoAP Content-Formats Registry
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+# CoAP option number to name mapping (RFC 7252)
+OPTIONS: dict[int, str] = {
+    1: "If-Match",
+    3: "Uri-Host",
+    4: "ETag",
+    5: "If-None-Match",
+    6: "Observe",  # RFC 7641
+    7: "Uri-Port",
+    8: "Location-Path",
+    11: "Uri-Path",
+    12: "Content-Format",
+    14: "Max-Age",
+    15: "Uri-Query",
+    17: "Accept",
+    20: "Location-Query",
+    23: "Block2",  # RFC 7959
+    27: "Block1",  # RFC 7959
+    28: "Size2",  # RFC 7959
+    35: "Proxy-Uri",
+    39: "Proxy-Scheme",
+    60: "Size1",  # RFC 7959
+}
+
+# CoAP content format codes (RFC 7252)
+CONTENT_FORMATS: dict[int, str] = {
+    0: "text/plain; charset=utf-8",
+    40: "application/link-format",
+    41: "application/xml",
+    42: "application/octet-stream",
+    47: "application/exi",
+    50: "application/json",
+    60: "application/cbor",
+    # Additional formats from IANA registry
+    100: "application/senml+json",
+    101: "application/sensml+json",
+    110: "application/senml+cbor",
+    111: "application/sensml+cbor",
+    112: "application/senml-exi",
+    113: "application/sensml-exi",
+    256: "application/coap-group+json",
+    10000: "application/pkcs7-mime; smime-type=server-generated-key",
+    10001: "application/pkcs7-mime; smime-type=certs-only",
+    10002: "application/pkcs8",
+    10003: "application/csrattrs",
+    10004: "application/pkcs10",
+    10005: "application/pkix-cert",
+}
+
+
+class OptionParser:
+    """Helper class for parsing CoAP options.
+
+    Provides methods for decoding option values based on their option number
+    and handling CoAP option delta encoding.
+
+    Example:
+        >>> parser = OptionParser()
+        >>> value = parser.decode_value(11, b"temperature")
+        >>> print(value)
+        'temperature'
+    """
+
+    # Empty format options (no value)
+    EMPTY_OPTIONS: ClassVar[set[int]] = {5}  # If-None-Match
+
+    # Opaque options (bytes)
+    OPAQUE_OPTIONS: ClassVar[set[int]] = {1, 4}  # If-Match, ETag
+
+    # String options (UTF-8)
+    STRING_OPTIONS: ClassVar[set[int]] = {3, 8, 11, 15, 20, 35, 39}
+
+    # Unsigned integer options
+    UINT_OPTIONS: ClassVar[set[int]] = {6, 7, 12, 14, 17, 23, 27, 28, 60}
+
+    @staticmethod
+    def decode_value(option_num: int, value: bytes) -> str | int | bytes:
+        """Decode option value based on option number.
+
+        Args:
+            option_num: CoAP option number.
+            value: Raw option value bytes.
+
+        Returns:
+            Decoded value as string, int, or bytes depending on option type.
+
+        Example:
+            >>> parser = OptionParser()
+            >>> parser.decode_value(11, b"sensor")
+            'sensor'
+            >>> parser.decode_value(12, b"\\x00\\x32")
+            50
+        """
+        if option_num in OptionParser.EMPTY_OPTIONS:
+            return b""
+
+        if not value:
+            # Empty value - return appropriate type
+            if option_num in OptionParser.STRING_OPTIONS:
+                return ""
+            if option_num in OptionParser.UINT_OPTIONS:
+                return 0
+            return b""
+
+        if option_num in OptionParser.STRING_OPTIONS:
+            try:
+                return value.decode("utf-8")
+            except UnicodeDecodeError:
+                return value
+
+        if option_num in OptionParser.UINT_OPTIONS:
+            return int.from_bytes(value, "big")
+
+        # Default to opaque (bytes)
+        return value
+
+    @staticmethod
+    def parse_extended_value(base: int, data: bytes, offset: int) -> tuple[int, int]:
+        """Parse extended delta or length value.
+
+        CoAP uses extended encoding for delta/length values >= 13:
+        - 13: value is (base value from next byte) + 13
+        - 14: value is (base value from next 2 bytes) + 269
+        - 15: reserved (payload marker or error)
+
+        Args:
+            base: Base value (0-15) from option header nibble.
+            data: Complete message data.
+            offset: Current offset in data.
+
+        Returns:
+            Tuple of (actual_value, bytes_consumed).
+
+        Raises:
+            ValueError: If extended format is invalid or data insufficient.
+
+        Example:
+            >>> parser = OptionParser()
+            >>> value, consumed = parser.parse_extended_value(13, b"\\x05\\x00", 0)
+            >>> value, consumed
+            (18, 1)
+        """
+        if base < 13:
+            return base, 0
+
+        if base == 13:
+            if len(data) < offset + 1:
+                raise ValueError("Insufficient data for extended option delta/length")
+            return data[offset] + 13, 1
+
+        if base == 14:
+            if len(data) < offset + 2:
+                raise ValueError("Insufficient data for extended option delta/length")
+            return int.from_bytes(data[offset : offset + 2], "big") + 269, 2
+
+        # base == 15
+        raise ValueError("Invalid option delta/length value (15)")
+
+
+def format_block_option(value: int) -> dict[str, Any]:
+    """Parse Block1/Block2 option value.
+
+    Block options encode: NUM (block number), M (more flag), SZX (size exponent).
+
+    Format (variable length, 1-3 bytes):
+        0 1 2 3 4 5 6 7
+       +-+-+-+-+-+-+-+-+
+       |  NUM  |M| SZX |
+       +-+-+-+-+-+-+-+-+
+
+    Args:
+        value: Block option value as unsigned integer.
+
+    Returns:
+        Dictionary with 'num' (block number), 'more' (more flag), and 'size' (block size).
+
+    Example:
+        >>> result = format_block_option(0x08)  # Block 0, no more, size 16
+        >>> result['num'], result['more'], result['size']
+        (0, False, 16)
+    """
+    num = value >> 4
+    more = bool((value >> 3) & 0x01)
+    szx = value & 0x07
+    size = 2 ** (szx + 4)  # Size = 2^(SZX+4), range: 16-1024 bytes
+
+    return {
+        "num": num,
+        "more": more,
+        "size": size,
+    }
+
+
+__all__ = [
+    "CONTENT_FORMATS",
+    "OPTIONS",
+    "OptionParser",
+    "format_block_option",
+]

oscura/iot/lorawan/__init__.py

@@ -0,0 +1,21 @@
+"""LoRaWAN protocol decoder package.
+
+Provides LoRaWAN MAC layer parsing and payload decryption support.
+"""
+
+from oscura.iot.lorawan.decoder import (
+    LoRaWANDecoder,
+    LoRaWANFrame,
+    LoRaWANKeys,
+    decode_lorawan_frame,
+)
+from oscura.iot.lorawan.mac_commands import MAC_COMMANDS, parse_mac_command
+
+__all__ = [
+    "MAC_COMMANDS",
+    "LoRaWANDecoder",
+    "LoRaWANFrame",
+    "LoRaWANKeys",
+    "decode_lorawan_frame",
+    "parse_mac_command",
+]

oscura/iot/lorawan/crypto.py

@@ -0,0 +1,206 @@
+"""LoRaWAN cryptographic operations.
+
+This module provides AES-128 encryption/decryption and CMAC operations
+for LoRaWAN payload security as defined in LoRaWAN Specification 1.0.3.
+
+Security:
+    Uses cryptography library (modern, actively maintained) instead of deprecated PyCrypto.
+    All cryptographic operations follow LoRaWAN 1.0.3 specification.
+
+References:
+    LoRaWAN Specification 1.0.3: https://lora-alliance.org/resource_hub/lorawan-specification-v1-0-3/
+    Section 4.3.3 - MAC Frame Payload Encryption (FRMPayload)
+    Section 4.4 - Message Integrity Code (MIC)
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+
+def decrypt_payload(
+    frm_payload: bytes,
+    key: bytes,
+    dev_addr: int,
+    fcnt: int,
+    direction: Literal["up", "down"],
+) -> bytes:
+    """Decrypt LoRaWAN FRMPayload using AES-128 in CTR mode.
+
+    Args:
+        frm_payload: Encrypted payload bytes.
+        key: AES-128 key (16 bytes) - AppSKey or NwkSKey.
+        dev_addr: Device address (4 bytes).
+        fcnt: Frame counter.
+        direction: Direction "up" (uplink) or "down" (downlink).
+
+    Returns:
+        Decrypted payload bytes.
+
+    Raises:
+        ValueError: If key is not 16 bytes.
+        ImportError: If cryptography library is not available.
+
+    Example:
+        >>> key = bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3C")
+        >>> encrypted = bytes.fromhex("0123456789ABCDEF")
+        >>> decrypted = decrypt_payload(encrypted, key, 0x01020304, 1, "up")
+    """
+    try:
+        from cryptography.hazmat.backends import default_backend
+        from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+    except ImportError as exc:
+        msg = (
+            "cryptography library is required for LoRaWAN encryption. "
+            "Install with: pip install cryptography"
+        )
+        raise ImportError(msg) from exc
+
+    if len(key) != 16:
+        msg = f"Key must be 16 bytes, got {len(key)}"
+        raise ValueError(msg)
+
+    if len(frm_payload) == 0:
+        return b""
+
+    # Direction byte: 0x00 for uplink, 0x01 for downlink
+    dir_byte = 0x00 if direction == "up" else 0x01
+
+    # Number of 16-byte blocks needed
+    num_blocks = (len(frm_payload) + 15) // 16
+
+    # Generate keystream by encrypting counter blocks
+    keystream = b""
+    for i in range(num_blocks):
+        # Build encryption block A_i (16 bytes)
+        # A_i = 0x01 | 0x00000000 | Dir | DevAddr | FCnt | 0x00 | i
+        a = bytearray(16)
+        a[0] = 0x01  # Encryption flag
+        # a[1:5] = 0x00000000 (already zero)
+        a[5] = dir_byte
+        a[6:10] = dev_addr.to_bytes(4, "little")
+        a[10:14] = fcnt.to_bytes(4, "little")
+        # a[14] = 0x00 (already zero)
+        a[15] = i + 1
+
+        # Encrypt the block using AES in ECB mode
+        # Security: ECB mode is required by LoRaWAN spec (Section 4.3.3)
+        # Each counter block is unique, so ECB mode is safe here
+        cipher = Cipher(algorithms.AES(key), modes.ECB(), backend=default_backend())
+        encryptor = cipher.encryptor()
+        keystream += encryptor.update(bytes(a)) + encryptor.finalize()
+
+    # XOR payload with keystream
+    decrypted = bytes(
+        p ^ k for p, k in zip(frm_payload, keystream[: len(frm_payload)], strict=False)
+    )
+    return decrypted
+
+
+def compute_mic(
+    data: bytes,
+    key: bytes,
+    dev_addr: int,
+    fcnt: int,
+    direction: Literal["up", "down"],
+) -> int:
+    """Compute LoRaWAN Message Integrity Code (MIC) using AES-CMAC.
+
+    Args:
+        data: Message data (MHDR | FHDR | FPort | FRMPayload).
+        key: Network session key (NwkSKey, 16 bytes).
+        dev_addr: Device address (4 bytes).
+        fcnt: Frame counter.
+        direction: Direction "up" (uplink) or "down" (downlink).
+
+    Returns:
+        32-bit MIC value.
+
+    Raises:
+        ValueError: If key is not 16 bytes.
+        ImportError: If cryptography library is not available.
+
+    Example:
+        >>> key = bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3C")
+        >>> data = bytes.fromhex("40010203040001000100")
+        >>> mic = compute_mic(data, key, 0x01020304, 1, "up")
+    """
+    try:
+        from cryptography.hazmat.backends import default_backend
+        from cryptography.hazmat.primitives import cmac
+        from cryptography.hazmat.primitives.ciphers import algorithms
+    except ImportError as exc:
+        msg = (
+            "cryptography library is required for LoRaWAN MIC computation. "
+            "Install with: pip install cryptography"
+        )
+        raise ImportError(msg) from exc
+
+    if len(key) != 16:
+        msg = f"Key must be 16 bytes, got {len(key)}"
+        raise ValueError(msg)
+
+    # Direction byte: 0x00 for uplink, 0x01 for downlink
+    dir_byte = 0x00 if direction == "up" else 0x01
+
+    # Build MIC computation block B_0 (16 bytes)
+    # B_0 = 0x49 | 0x00000000 | Dir | DevAddr | FCnt | 0x00 | len(msg)
+    b0 = bytearray(16)
+    b0[0] = 0x49  # MIC flag
+    # b0[1:5] = 0x00000000 (already zero)
+    b0[5] = dir_byte
+    b0[6:10] = dev_addr.to_bytes(4, "little")
+    b0[10:14] = fcnt.to_bytes(4, "little")
+    # b0[14] = 0x00 (already zero)
+    b0[15] = len(data)
+
+    # Compute CMAC over B_0 | msg
+    c = cmac.CMAC(algorithms.AES(key), backend=default_backend())
+    c.update(bytes(b0))
+    c.update(data)
+    mac = c.finalize()
+
+    # Return first 4 bytes as 32-bit integer (little-endian)
+    mic = int.from_bytes(mac[:4], "little")
+    return mic
+
+
+def verify_mic(
+    data: bytes,
+    received_mic: int,
+    key: bytes,
+    dev_addr: int,
+    fcnt: int,
+    direction: Literal["up", "down"],
+) -> bool:
+    """Verify LoRaWAN Message Integrity Code (MIC).
+
+    Args:
+        data: Message data (MHDR | FHDR | FPort | FRMPayload).
+        received_mic: Received MIC value.
+        key: Network session key (NwkSKey, 16 bytes).
+        dev_addr: Device address (4 bytes).
+        fcnt: Frame counter.
+        direction: Direction "up" (uplink) or "down" (downlink).
+
+    Returns:
+        True if MIC is valid, False otherwise.
+
+    Example:
+        >>> key = bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3C")
+        >>> data = bytes.fromhex("40010203040001000100")
+        >>> is_valid = verify_mic(data, 0x12345678, key, 0x01020304, 1, "up")
+    """
+    try:
+        computed_mic = compute_mic(data, key, dev_addr, fcnt, direction)
+        return computed_mic == received_mic
+    except (ImportError, ValueError):
+        # If crypto is unavailable, we can't verify
+        return False
+
+
+__all__ = [
+    "compute_mic",
+    "decrypt_payload",
+    "verify_mic",
+]