blerpc-protocol 0.8.0__py3-none-any.whl

blerpc_protocol/__init__.py

@@ -0,0 +1,62 @@
+"""blerpc-protocol: Container and command protocol layers for BLE RPC."""
+
+from blerpc_protocol.command import CommandPacket, CommandType
+from blerpc_protocol.container import (
+    ATT_OVERHEAD,
+    CAPABILITY_FLAG_ENCRYPTION_SUPPORTED,
+    CONTROL_HEADER_SIZE,
+    FIRST_HEADER_SIZE,
+    SUBSEQUENT_HEADER_SIZE,
+    Container,
+    ContainerAssembler,
+    ContainerSplitter,
+    ContainerType,
+    ControlCmd,
+    make_capabilities_request,
+    make_capabilities_response,
+    make_error_response,
+    make_key_exchange,
+    make_stream_end_c2p,
+    make_stream_end_p2c,
+    make_timeout_request,
+    make_timeout_response,
+)
+from blerpc_protocol.crypto import (
+    BlerpcCrypto,
+    BlerpcCryptoSession,
+    CentralKeyExchange,
+    KnownKeyStore,
+    PeripheralKeyExchange,
+    central_perform_key_exchange,
+    tofu_verify,
+)
+
+__all__ = [
+    "ATT_OVERHEAD",
+    "BlerpcCrypto",
+    "BlerpcCryptoSession",
+    "CAPABILITY_FLAG_ENCRYPTION_SUPPORTED",
+    "CentralKeyExchange",
+    "CONTROL_HEADER_SIZE",
+    "FIRST_HEADER_SIZE",
+    "SUBSEQUENT_HEADER_SIZE",
+    "CommandPacket",
+    "CommandType",
+    "Container",
+    "ContainerAssembler",
+    "ContainerSplitter",
+    "ContainerType",
+    "ControlCmd",
+    "make_capabilities_request",
+    "make_capabilities_response",
+    "make_error_response",
+    "make_key_exchange",
+    "make_stream_end_c2p",
+    "make_stream_end_p2c",
+    "make_timeout_request",
+    "make_timeout_response",
+    "PeripheralKeyExchange",
+    "KnownKeyStore",
+    "central_perform_key_exchange",
+    "tofu_verify",
+]

blerpc_protocol/command.py

@@ -0,0 +1,76 @@
+"""Command encode/decode layer for blerpc.
+
+Command format (bits):
+| type(1) | reserved(7) | cmd_name_len(8) | cmd_name(N*8) |
+| data_len(16) | data(data_len*8) |
+
+- type: 0=request, 1=response
+- cmd_name: ASCII command name
+- data_len: little-endian uint16
+- data: protobuf-encoded bytes
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from enum import IntEnum
+
+
+class CommandType(IntEnum):
+    REQUEST = 0
+    RESPONSE = 1
+
+
+@dataclass
+class CommandPacket:
+    """A single command packet."""
+
+    cmd_type: CommandType
+    cmd_name: str
+    data: bytes = b""
+
+    def serialize(self) -> bytes:
+        """Serialize command to bytes."""
+        name_bytes = self.cmd_name.encode("ascii")
+        if len(name_bytes) > 255:
+            raise ValueError(f"cmd_name too long: {len(name_bytes)} > 255")
+        if len(self.data) > 65535:
+            raise ValueError(f"data too long: {len(self.data)} > 65535")
+
+        # Byte 0: type in MSB (bit 7), reserved bits 6-0 = 0
+        byte0 = (self.cmd_type & 0x01) << 7
+        return (
+            bytes([byte0])
+            + struct.pack("<B", len(name_bytes))
+            + name_bytes
+            + struct.pack("<H", len(self.data))
+            + self.data
+        )
+
+    @staticmethod
+    def deserialize(data: bytes) -> CommandPacket:
+        """Deserialize bytes into a CommandPacket."""
+        if len(data) < 2:
+            raise ValueError(f"Command packet too short: {len(data)} bytes")
+
+        # Byte 0: type in MSB
+        cmd_type = CommandType((data[0] >> 7) & 0x01)
+        cmd_name_len = data[1]
+
+        offset = 2
+        if len(data) < offset + cmd_name_len + 2:
+            raise ValueError("Command packet truncated")
+
+        cmd_name = data[offset : offset + cmd_name_len].decode("ascii")
+        offset += cmd_name_len
+
+        data_len = struct.unpack_from("<H", data, offset)[0]
+        offset += 2
+
+        payload = data[offset : offset + data_len]
+        return CommandPacket(
+            cmd_type=cmd_type,
+            cmd_name=cmd_name,
+            data=payload,
+        )

blerpc_protocol/container.py

@@ -0,0 +1,387 @@
+"""Container split/merge/control layer for blerpc.
+
+Container format (bits):
+| transaction_id(8) | sequence_number(8) | type(2)|control_cmd(4)|reserved(2) |
+| total_length(16 or 0) | payload_len(8) | payload(variable) |
+
+type=0b00 (FIRST): has total_length, header = 6 bytes
+type=0b01 (SUBSEQUENT): no total_length, header = 4 bytes
+type=0b11 (CONTROL): no total_length, header = 4 bytes
+
+All multi-byte fields are little-endian.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+
+class ContainerType(IntEnum):
+    FIRST = 0b00
+    SUBSEQUENT = 0b01
+    CONTROL = 0b11
+    # Sentinel for the one undefined 2-bit type value (0b10). Never emitted by
+    # senders; produced when parsing an unrecognized frame so a hostile peer
+    # cannot crash the parser with an out-of-range type. Treated as droppable
+    # by the assembler and control handlers.
+    UNKNOWN = 0b10
+
+
+class ControlCmd(IntEnum):
+    NONE = 0x0
+    TIMEOUT = 0x1
+    STREAM_END_C2P = 0x2
+    STREAM_END_P2C = 0x3
+    CAPABILITIES = 0x4
+    ERROR = 0x5
+    KEY_EXCHANGE = 0x6
+    # Sentinel for any unrecognized control command (0x7-0xF). Never emitted by
+    # senders; unknown commands parse to this value and are dropped by handlers
+    # rather than raising.
+    UNKNOWN = 0xF
+
+    @classmethod
+    def _missing_(cls, value: object) -> "ControlCmd":
+        # A 4-bit wire field can carry values with no defined member; map them
+        # to UNKNOWN instead of raising ValueError on attacker-controlled input.
+        return cls.UNKNOWN
+
+
+# Error codes for ControlCmd.ERROR
+BLERPC_ERROR_RESPONSE_TOO_LARGE = 0x01
+BLERPC_ERROR_BUSY = 0x02
+
+# Capabilities flags (bit field)
+CAPABILITY_FLAG_ENCRYPTION_SUPPORTED = 0x0001
+
+
+# Header sizes
+FIRST_HEADER_SIZE = 6  # txn_id(1) + seq(1) + flags(1) + total_len(2) + payload_len(1)
+SUBSEQUENT_HEADER_SIZE = 4  # txn_id(1) + seq(1) + flags(1) + payload_len(1)
+CONTROL_HEADER_SIZE = 4  # txn_id(1) + seq(1) + flags(1) + payload_len(1)
+
+ATT_OVERHEAD = 3  # ATT header bytes subtracted from MTU
+
+
+def _pack_flags(
+    container_type: ContainerType, control_cmd: ControlCmd = ControlCmd.NONE
+) -> int:
+    """Pack type(2) | control_cmd(4) | reserved(2) into a single byte."""
+    return ((container_type & 0x03) << 6) | ((control_cmd & 0x0F) << 2)
+
+
+def _unpack_flags(flags_byte: int) -> tuple[ContainerType, ControlCmd]:
+    """Unpack flags byte into (type, control_cmd)."""
+    container_type = ContainerType((flags_byte >> 6) & 0x03)
+    control_cmd = ControlCmd((flags_byte >> 2) & 0x0F)
+    return container_type, control_cmd
+
+
+@dataclass
+class Container:
+    """A single container packet."""
+
+    transaction_id: int
+    sequence_number: int
+    container_type: ContainerType
+    control_cmd: ControlCmd = ControlCmd.NONE
+    total_length: int = 0  # Only meaningful for FIRST
+    payload: bytes = b""
+
+    def serialize(self) -> bytes:
+        """Serialize container to bytes."""
+        flags = _pack_flags(self.container_type, self.control_cmd)
+
+        if self.container_type == ContainerType.FIRST:
+            header = struct.pack(
+                "<BBBHB",
+                self.transaction_id,
+                self.sequence_number,
+                flags,
+                self.total_length,
+                len(self.payload),
+            )
+        else:
+            header = struct.pack(
+                "<BBBB",
+                self.transaction_id,
+                self.sequence_number,
+                flags,
+                len(self.payload),
+            )
+        return header + self.payload
+
+    @staticmethod
+    def deserialize(data: bytes) -> Container:
+        """Deserialize bytes into a Container."""
+        if len(data) < 4:
+            raise ValueError(f"Container too short: {len(data)} bytes")
+
+        transaction_id = data[0]
+        sequence_number = data[1]
+        container_type, control_cmd = _unpack_flags(data[2])
+
+        if container_type == ContainerType.FIRST:
+            if len(data) < FIRST_HEADER_SIZE:
+                raise ValueError(f"FIRST container too short: {len(data)} bytes")
+            total_length = struct.unpack_from("<H", data, 3)[0]
+            payload_len = data[5]
+            payload = data[FIRST_HEADER_SIZE : FIRST_HEADER_SIZE + payload_len]
+        else:
+            total_length = 0
+            payload_len = data[3]
+            header_size = SUBSEQUENT_HEADER_SIZE
+            payload = data[header_size : header_size + payload_len]
+
+        return Container(
+            transaction_id=transaction_id,
+            sequence_number=sequence_number,
+            container_type=container_type,
+            control_cmd=control_cmd,
+            total_length=total_length,
+            payload=payload,
+        )
+
+
+class ContainerSplitter:
+    """Splits a payload into containers respecting MTU."""
+
+    def __init__(self, mtu: int = 247):
+        self._mtu = mtu
+        self._transaction_counter = 0
+
+    @property
+    def effective_mtu(self) -> int:
+        """Usable bytes per BLE packet (MTU - ATT overhead)."""
+        return self._mtu - ATT_OVERHEAD
+
+    def next_transaction_id(self) -> int:
+        tid = self._transaction_counter
+        self._transaction_counter = (self._transaction_counter + 1) & 0xFF
+        return tid
+
+    def split(
+        self, payload: bytes, transaction_id: int | None = None
+    ) -> list[Container]:
+        """Split payload into a list of containers.
+
+        Raises ValueError if payload is too large for 8-bit
+        sequence_number (>255 containers).
+        """
+        if transaction_id is None:
+            transaction_id = self.next_transaction_id()
+
+        total_length = len(payload)
+        if total_length > 65535:
+            raise ValueError(f"Payload too large: {total_length} > 65535")
+        containers: list[Container] = []
+
+        # First container
+        first_max_payload = self.effective_mtu - FIRST_HEADER_SIZE
+        first_payload = payload[:first_max_payload]
+        containers.append(
+            Container(
+                transaction_id=transaction_id,
+                sequence_number=0,
+                container_type=ContainerType.FIRST,
+                total_length=total_length,
+                payload=first_payload,
+            )
+        )
+
+        offset = len(first_payload)
+        seq = 1
+
+        # Subsequent containers
+        subsequent_max_payload = self.effective_mtu - SUBSEQUENT_HEADER_SIZE
+        while offset < total_length:
+            if seq > 255:
+                raise ValueError(
+                    f"Payload requires more than 256 containers (seq={seq}), "
+                    "exceeding 8-bit sequence_number limit"
+                )
+            chunk = payload[offset : offset + subsequent_max_payload]
+            containers.append(
+                Container(
+                    transaction_id=transaction_id,
+                    sequence_number=seq,
+                    container_type=ContainerType.SUBSEQUENT,
+                    payload=chunk,
+                )
+            )
+            offset += len(chunk)
+            seq += 1
+
+        return containers
+
+
+class ContainerAssembler:
+    """Reassembles containers into a complete payload."""
+
+    def __init__(self):
+        self._transactions: dict[int, _AssemblyState] = {}
+
+    def feed(self, container: Container) -> bytes | None:
+        """Feed a container. Returns complete payload when done, else None."""
+        if container.container_type == ContainerType.CONTROL:
+            return None  # Control containers are handled separately
+
+        tid = container.transaction_id
+
+        if container.container_type == ContainerType.FIRST:
+            self._transactions[tid] = _AssemblyState(
+                total_length=container.total_length,
+                expected_seq=1,
+                fragments=[container.payload],
+                received_length=len(container.payload),
+            )
+        elif tid in self._transactions:
+            state = self._transactions[tid]
+            if container.sequence_number != state.expected_seq:
+                # Sequence gap — discard entire transaction
+                del self._transactions[tid]
+                return None
+            state.fragments.append(container.payload)
+            state.received_length += len(container.payload)
+            state.expected_seq += 1
+        else:
+            # Subsequent without a FIRST — ignore
+            return None
+
+        state = self._transactions[tid]
+        if state.received_length >= state.total_length:
+            payload = b"".join(state.fragments)[: state.total_length]
+            del self._transactions[tid]
+            return payload
+
+        return None
+
+    def reset(self):
+        """Clear all pending assembly state."""
+        self._transactions.clear()
+
+
+@dataclass
+class _AssemblyState:
+    total_length: int
+    expected_seq: int
+    fragments: list[bytes] = field(default_factory=list)
+    received_length: int = 0
+
+
+def make_timeout_request(transaction_id: int, sequence_number: int = 0) -> Container:
+    """Create a timeout request control container (Central -> Peripheral)."""
+    return Container(
+        transaction_id=transaction_id,
+        sequence_number=sequence_number,
+        container_type=ContainerType.CONTROL,
+        control_cmd=ControlCmd.TIMEOUT,
+        payload=b"",
+    )
+
+
+def make_timeout_response(
+    transaction_id: int, timeout_ms: int, sequence_number: int = 0
+) -> Container:
+    """Create a timeout response control container (Peripheral -> Central)."""
+    return Container(
+        transaction_id=transaction_id,
+        sequence_number=sequence_number,
+        container_type=ContainerType.CONTROL,
+        control_cmd=ControlCmd.TIMEOUT,
+        payload=struct.pack("<H", timeout_ms),
+    )
+
+
+def make_stream_end_c2p(transaction_id: int, sequence_number: int = 0) -> Container:
+    """Create stream end container (Central -> Peripheral)."""
+    return Container(
+        transaction_id=transaction_id,
+        sequence_number=sequence_number,
+        container_type=ContainerType.CONTROL,
+        control_cmd=ControlCmd.STREAM_END_C2P,
+        payload=b"",
+    )
+
+
+def make_stream_end_p2c(transaction_id: int, sequence_number: int = 0) -> Container:
+    """Create stream end container (Peripheral -> Central)."""
+    return Container(
+        transaction_id=transaction_id,
+        sequence_number=sequence_number,
+        container_type=ContainerType.CONTROL,
+        control_cmd=ControlCmd.STREAM_END_P2C,
+        payload=b"",
+    )
+
+
+def make_capabilities_request(
+    transaction_id: int,
+    max_request_payload_size: int = 0,
+    max_response_payload_size: int = 0,
+    flags: int = 0,
+    sequence_number: int = 0,
+) -> Container:
+    """Create a capabilities request control container (Central -> Peripheral).
+
+    6-byte payload: [max_req:u16LE][max_resp:u16LE][flags:u16LE]
+    """
+    return Container(
+        transaction_id=transaction_id,
+        sequence_number=sequence_number,
+        container_type=ContainerType.CONTROL,
+        control_cmd=ControlCmd.CAPABILITIES,
+        payload=struct.pack(
+            "<HHH", max_request_payload_size, max_response_payload_size, flags
+        ),
+    )
+
+
+def make_capabilities_response(
+    transaction_id: int,
+    max_request_payload_size: int,
+    max_response_payload_size: int,
+    flags: int = 0,
+    sequence_number: int = 0,
+) -> Container:
+    """Create a capabilities response control container (Peripheral -> Central).
+
+    6-byte payload: [max_req:u16LE][max_resp:u16LE][flags:u16LE]
+    """
+    return Container(
+        transaction_id=transaction_id,
+        sequence_number=sequence_number,
+        container_type=ContainerType.CONTROL,
+        control_cmd=ControlCmd.CAPABILITIES,
+        payload=struct.pack(
+            "<HHH", max_request_payload_size, max_response_payload_size, flags
+        ),
+    )
+
+
+def make_error_response(
+    transaction_id: int, error_code: int, sequence_number: int = 0
+) -> Container:
+    """Create an error control container (Peripheral -> Central)."""
+    return Container(
+        transaction_id=transaction_id,
+        sequence_number=sequence_number,
+        container_type=ContainerType.CONTROL,
+        control_cmd=ControlCmd.ERROR,
+        payload=bytes([error_code]),
+    )
+
+
+def make_key_exchange(
+    transaction_id: int, payload: bytes, sequence_number: int = 0
+) -> Container:
+    """Create a key exchange control container."""
+    return Container(
+        transaction_id=transaction_id,
+        sequence_number=sequence_number,
+        container_type=ContainerType.CONTROL,
+        control_cmd=ControlCmd.KEY_EXCHANGE,
+        payload=payload,
+    )

blerpc_protocol/crypto.py

@@ -0,0 +1,598 @@
+"""E2E encryption for blerpc using X25519, Ed25519, AES-128-GCM, HKDF-SHA256."""
+
+from __future__ import annotations
+
+import os
+import struct
+import threading
+from collections.abc import Awaitable, Callable
+from typing import Protocol
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.asymmetric.x25519 import (
+    X25519PrivateKey,
+    X25519PublicKey,
+)
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+# Direction bytes for nonce construction
+DIRECTION_C2P = 0x00
+DIRECTION_P2C = 0x01
+
+# Confirmation plaintexts
+CONFIRM_CENTRAL = b"BLERPC_CONFIRM_C"
+CONFIRM_PERIPHERAL = b"BLERPC_CONFIRM_P"
+
+# Key exchange step constants
+KEY_EXCHANGE_STEP1 = 0x01
+KEY_EXCHANGE_STEP2 = 0x02
+KEY_EXCHANGE_STEP3 = 0x03
+KEY_EXCHANGE_STEP4 = 0x04
+
+
+class BlerpcCrypto:
+    """Cryptographic operations for blerpc E2E encryption."""
+
+    @staticmethod
+    def generate_x25519_keypair() -> tuple[X25519PrivateKey, bytes]:
+        """Generate an X25519 key pair.
+
+        Returns (private_key, public_key_bytes_32).
+        """
+        private_key = X25519PrivateKey.generate()
+        public_bytes = private_key.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+        return private_key, public_bytes
+
+    @staticmethod
+    def x25519_public_bytes(private_key: X25519PrivateKey) -> bytes:
+        """Get the raw 32-byte public key from a private key."""
+        return private_key.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+
+    @staticmethod
+    def x25519_shared_secret(
+        private_key: X25519PrivateKey, peer_public_bytes: bytes
+    ) -> bytes:
+        """Compute X25519 shared secret (32 bytes)."""
+        peer_public = X25519PublicKey.from_public_bytes(peer_public_bytes)
+        return private_key.exchange(peer_public)
+
+    @staticmethod
+    def derive_session_key(
+        shared_secret: bytes,
+        central_pubkey: bytes,
+        peripheral_pubkey: bytes,
+    ) -> bytes:
+        """Derive 16-byte AES-128 session key using HKDF-SHA256.
+
+        salt = central_pubkey || peripheral_pubkey (64 bytes)
+        info = b"blerpc-session-key"
+        """
+        hkdf = HKDF(
+            algorithm=hashes.SHA256(),
+            length=16,
+            salt=central_pubkey + peripheral_pubkey,
+            info=b"blerpc-session-key",
+        )
+        return hkdf.derive(shared_secret)
+
+    @staticmethod
+    def generate_ed25519_keypair() -> tuple[Ed25519PrivateKey, bytes]:
+        """Generate an Ed25519 key pair.
+
+        Returns (private_key, public_key_bytes_32).
+        """
+        private_key = Ed25519PrivateKey.generate()
+        public_bytes = private_key.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+        return private_key, public_bytes
+
+    @staticmethod
+    def ed25519_public_bytes(private_key: Ed25519PrivateKey) -> bytes:
+        """Get the raw 32-byte public key from a private key."""
+        return private_key.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+
+    @staticmethod
+    def ed25519_sign(private_key: Ed25519PrivateKey, message: bytes) -> bytes:
+        """Sign a message with Ed25519. Returns 64-byte signature."""
+        return private_key.sign(message)
+
+    @staticmethod
+    def ed25519_verify(
+        public_key_bytes: bytes, message: bytes, signature: bytes
+    ) -> bool:
+        """Verify an Ed25519 signature. Returns True if valid."""
+        try:
+            public_key = Ed25519PublicKey.from_public_bytes(public_key_bytes)
+            public_key.verify(signature, message)
+            return True
+        except (ValueError, InvalidSignature):
+            return False
+
+    @staticmethod
+    def ed25519_private_from_bytes(data: bytes) -> Ed25519PrivateKey:
+        """Load Ed25519 private key from raw 32-byte seed."""
+        return Ed25519PrivateKey.from_private_bytes(data)
+
+    @staticmethod
+    def x25519_private_from_bytes(data: bytes) -> X25519PrivateKey:
+        """Load X25519 private key from raw 32 bytes."""
+        return X25519PrivateKey.from_private_bytes(data)
+
+    @staticmethod
+    def _build_nonce(counter: int, direction: int) -> bytes:
+        """Build 12-byte AES-GCM nonce: counter(4B) || direction(1B) || zeros(7B)."""
+        return struct.pack("<IB", counter, direction) + b"\x00" * 7
+
+    @staticmethod
+    def encrypt_command(
+        session_key: bytes, counter: int, direction: int, plaintext: bytes
+    ) -> bytes:
+        """Encrypt a command payload.
+
+        Returns: [counter:4BLE][ciphertext:NB][tag:16B]
+        """
+        nonce = BlerpcCrypto._build_nonce(counter, direction)
+        aesgcm = AESGCM(session_key)
+        ct_and_tag = aesgcm.encrypt(nonce, plaintext, None)
+        return struct.pack("<I", counter) + ct_and_tag
+
+    @staticmethod
+    def decrypt_command(
+        session_key: bytes, direction: int, data: bytes
+    ) -> tuple[int, bytes]:
+        """Decrypt a command payload.
+
+        Input: [counter:4BLE][ciphertext:NB][tag:16B]
+        Returns: (counter, plaintext)
+        """
+        if len(data) < 20:
+            raise ValueError(f"Encrypted payload too short: {len(data)}")
+        counter = struct.unpack_from("<I", data, 0)[0]
+        ct_and_tag = data[4:]
+        nonce = BlerpcCrypto._build_nonce(counter, direction)
+        aesgcm = AESGCM(session_key)
+        plaintext = aesgcm.decrypt(nonce, ct_and_tag, None)
+        return counter, plaintext
+
+    @staticmethod
+    def encrypt_confirmation(session_key: bytes, message: bytes) -> bytes:
+        """Encrypt a confirmation message for key exchange step 3/4.
+
+        Returns: [nonce:12B][ciphertext:16B][tag:16B] = 44 bytes
+        """
+        nonce = os.urandom(12)
+        aesgcm = AESGCM(session_key)
+        ct_and_tag = aesgcm.encrypt(nonce, message, None)
+        return nonce + ct_and_tag
+
+    @staticmethod
+    def decrypt_confirmation(session_key: bytes, data: bytes) -> bytes:
+        """Decrypt a confirmation message from key exchange step 3/4.
+
+        Input: [nonce:12B][ciphertext:16B][tag:16B] = 44 bytes
+        Returns: plaintext (16 bytes)
+        """
+        if len(data) < 44:
+            raise ValueError(f"Confirmation too short: {len(data)}")
+        nonce = data[:12]
+        ct_and_tag = data[12:]
+        aesgcm = AESGCM(session_key)
+        return aesgcm.decrypt(nonce, ct_and_tag, None)
+
+    @staticmethod
+    def build_step1_payload(central_x25519_pubkey: bytes) -> bytes:
+        """Build KEY_EXCHANGE step 1 payload (33 bytes).
+
+        [step:u8=0x01][central_x25519_pubkey:32B]
+        """
+        return bytes([KEY_EXCHANGE_STEP1]) + central_x25519_pubkey
+
+    @staticmethod
+    def parse_step1_payload(data: bytes) -> bytes:
+        """Parse KEY_EXCHANGE step 1 payload.
+
+        Returns central_x25519_pubkey (32 bytes).
+        """
+        if len(data) < 33 or data[0] != KEY_EXCHANGE_STEP1:
+            raise ValueError("Invalid step 1 payload")
+        return data[1:33]
+
+    @staticmethod
+    def build_step2_payload(
+        peripheral_x25519_pubkey: bytes,
+        ed25519_signature: bytes,
+        peripheral_ed25519_pubkey: bytes,
+    ) -> bytes:
+        """Build KEY_EXCHANGE step 2 payload (129 bytes).
+
+        [step:u8=0x02][peripheral_x25519_pubkey:32B][ed25519_signature:64B]
+        [peripheral_ed25519_pubkey:32B]
+        """
+        return (
+            bytes([KEY_EXCHANGE_STEP2])
+            + peripheral_x25519_pubkey
+            + ed25519_signature
+            + peripheral_ed25519_pubkey
+        )
+
+    @staticmethod
+    def parse_step2_payload(
+        data: bytes,
+    ) -> tuple[bytes, bytes, bytes]:
+        """Parse KEY_EXCHANGE step 2 payload.
+
+        Returns (peripheral_x25519_pubkey, ed25519_signature,
+                 peripheral_ed25519_pubkey).
+        """
+        if len(data) < 129 or data[0] != KEY_EXCHANGE_STEP2:
+            raise ValueError("Invalid step 2 payload")
+        peripheral_x25519_pubkey = data[1:33]
+        ed25519_signature = data[33:97]
+        peripheral_ed25519_pubkey = data[97:129]
+        return peripheral_x25519_pubkey, ed25519_signature, peripheral_ed25519_pubkey
+
+    @staticmethod
+    def build_step3_payload(confirmation_encrypted: bytes) -> bytes:
+        """Build KEY_EXCHANGE step 3 payload (45 bytes).
+
+        [step:u8=0x03][nonce:12B][ciphertext:16B][tag:16B]
+        """
+        return bytes([KEY_EXCHANGE_STEP3]) + confirmation_encrypted
+
+    @staticmethod
+    def parse_step3_payload(data: bytes) -> bytes:
+        """Parse KEY_EXCHANGE step 3 payload.
+
+        Returns the encrypted confirmation (44 bytes).
+        """
+        if len(data) < 45 or data[0] != KEY_EXCHANGE_STEP3:
+            raise ValueError("Invalid step 3 payload")
+        return data[1:45]
+
+    @staticmethod
+    def build_step4_payload(confirmation_encrypted: bytes) -> bytes:
+        """Build KEY_EXCHANGE step 4 payload (45 bytes).
+
+        [step:u8=0x04][nonce:12B][ciphertext:16B][tag:16B]
+        """
+        return bytes([KEY_EXCHANGE_STEP4]) + confirmation_encrypted
+
+    @staticmethod
+    def parse_step4_payload(data: bytes) -> bytes:
+        """Parse KEY_EXCHANGE step 4 payload.
+
+        Returns the encrypted confirmation (44 bytes).
+        """
+        if len(data) < 45 or data[0] != KEY_EXCHANGE_STEP4:
+            raise ValueError("Invalid step 4 payload")
+        return data[1:45]
+
+
+class BlerpcCryptoSession:
+    """Encrypt/decrypt with counter management and replay detection."""
+
+    def __init__(self, session_key: bytes, is_central: bool):
+        self._session_key = session_key
+        self._tx_counter = 0
+        self._rx_counter = 0
+        self._rx_first_done = False
+        self._tx_direction = DIRECTION_C2P if is_central else DIRECTION_P2C
+        self._rx_direction = DIRECTION_P2C if is_central else DIRECTION_C2P
+        self._lock = threading.Lock()
+
+    def encrypt(self, plaintext: bytes) -> bytes:
+        with self._lock:
+            if self._tx_counter >= 0xFFFFFFFF:
+                raise RuntimeError("TX counter overflow: session must be rekeyed")
+            encrypted = BlerpcCrypto.encrypt_command(
+                self._session_key, self._tx_counter, self._tx_direction, plaintext
+            )
+            self._tx_counter += 1
+            return encrypted
+
+    def decrypt(self, data: bytes) -> bytes:
+        with self._lock:
+            counter, plaintext = BlerpcCrypto.decrypt_command(
+                self._session_key, self._rx_direction, data
+            )
+            if self._rx_first_done and counter <= self._rx_counter:
+                raise RuntimeError(f"Replay detected: counter={counter}")
+            self._rx_counter = counter
+            self._rx_first_done = True
+            return plaintext
+
+
+class CentralKeyExchange:
+    """Central-side key exchange state machine.
+
+    Usage:
+        kx = CentralKeyExchange()
+        step1_payload = kx.start()                          # send to peripheral
+        step3_payload = kx.process_step2(step2_payload)     # send to peripheral
+        session       = kx.finish(step4_payload)           # BlerpcCryptoSession
+    """
+
+    def __init__(self) -> None:
+        self._x25519_privkey: X25519PrivateKey | None = None
+        self._x25519_pubkey: bytes | None = None
+        self._session_key: bytes | None = None
+        self._state = 0
+
+    def start(self) -> bytes:
+        """Generate ephemeral X25519 keypair and return step 1 payload."""
+        if self._state != 0:
+            raise RuntimeError("Invalid state for start()")
+        self._x25519_privkey, self._x25519_pubkey = (
+            BlerpcCrypto.generate_x25519_keypair()
+        )
+        self._state = 1
+        return BlerpcCrypto.build_step1_payload(self._x25519_pubkey)
+
+    def process_step2(
+        self,
+        step2_payload: bytes,
+        verify_key_cb: Callable[[bytes], bool] | None = None,
+    ) -> bytes:
+        """Parse step 2, verify signature, derive session key, return step 3 payload.
+
+        Args:
+            step2_payload: Raw step 2 payload from peripheral.
+            verify_key_cb: Optional callback receiving the peripheral's Ed25519 public
+                key (32 bytes). Return True to accept, False to reject (e.g. TOFU).
+                If None, any valid signature is accepted.
+
+        Raises:
+            ValueError: If signature verification fails or verify_key_cb rejects.
+        """
+        if self._state != 1:
+            raise RuntimeError("Invalid state for process_step2()")
+        periph_x25519_pub, signature, periph_ed25519_pub = (
+            BlerpcCrypto.parse_step2_payload(step2_payload)
+        )
+
+        sign_msg = self._x25519_pubkey + periph_x25519_pub
+        if not BlerpcCrypto.ed25519_verify(periph_ed25519_pub, sign_msg, signature):
+            raise ValueError("Ed25519 signature verification failed")
+
+        if verify_key_cb is not None and not verify_key_cb(periph_ed25519_pub):
+            raise ValueError("Peripheral key rejected by verify callback")
+
+        shared_secret = BlerpcCrypto.x25519_shared_secret(
+            self._x25519_privkey, periph_x25519_pub
+        )
+        self._session_key = BlerpcCrypto.derive_session_key(
+            shared_secret, self._x25519_pubkey, periph_x25519_pub
+        )
+
+        encrypted_confirm = BlerpcCrypto.encrypt_confirmation(
+            self._session_key, CONFIRM_CENTRAL
+        )
+        self._state = 2
+        return BlerpcCrypto.build_step3_payload(encrypted_confirm)
+
+    def finish(self, step4_payload: bytes) -> BlerpcCryptoSession:
+        """Parse step 4, verify peripheral confirmation, return session.
+
+        Raises:
+            ValueError: If confirmation verification fails.
+        """
+        if self._state != 2:
+            raise RuntimeError("Invalid state for finish()")
+        encrypted_periph = BlerpcCrypto.parse_step4_payload(step4_payload)
+        plaintext = BlerpcCrypto.decrypt_confirmation(
+            self._session_key, encrypted_periph
+        )
+        if plaintext != CONFIRM_PERIPHERAL:
+            raise ValueError("Peripheral confirmation mismatch")
+
+        return BlerpcCryptoSession(self._session_key, is_central=True)
+
+
+class PeripheralKeyExchange:
+    """Peripheral-side key exchange state machine.
+
+    Usage:
+        kx = PeripheralKeyExchange(ed25519_privkey)
+        step2_payload          = kx.process_step1(step1_payload)  # send to central
+        step4_payload, session = kx.process_step3(step3_payload)  # send + session
+    """
+
+    def __init__(
+        self,
+        ed25519_privkey: Ed25519PrivateKey,
+    ) -> None:
+        self._ed25519_privkey = ed25519_privkey
+        self._ed25519_pubkey = BlerpcCrypto.ed25519_public_bytes(ed25519_privkey)
+        self._session_key: bytes | None = None
+        self._state = 0
+
+    def process_step1(self, step1_payload: bytes) -> bytes:
+        """Parse step 1, generate ephemeral X25519 keypair, sign,
+        derive session key, return step 2 payload."""
+        if self._state != 0:
+            raise RuntimeError("Invalid state for process_step1()")
+        central_x25519_pubkey = BlerpcCrypto.parse_step1_payload(step1_payload)
+
+        # Generate ephemeral X25519 keypair for forward secrecy
+        x25519_privkey, x25519_pubkey = BlerpcCrypto.generate_x25519_keypair()
+
+        sign_msg = central_x25519_pubkey + x25519_pubkey
+        signature = BlerpcCrypto.ed25519_sign(self._ed25519_privkey, sign_msg)
+
+        shared_secret = BlerpcCrypto.x25519_shared_secret(
+            x25519_privkey, central_x25519_pubkey
+        )
+        self._session_key = BlerpcCrypto.derive_session_key(
+            shared_secret, central_x25519_pubkey, x25519_pubkey
+        )
+
+        self._state = 1
+        return BlerpcCrypto.build_step2_payload(
+            x25519_pubkey, signature, self._ed25519_pubkey
+        )
+
+    def process_step3(self, step3_payload: bytes) -> tuple[bytes, BlerpcCryptoSession]:
+        """Parse step 3, verify confirmation, return (step4_payload, session).
+
+        Raises:
+            ValueError: If central confirmation verification fails.
+        """
+        if self._state != 1:
+            raise RuntimeError("Invalid state for process_step3()")
+        encrypted = BlerpcCrypto.parse_step3_payload(step3_payload)
+        plaintext = BlerpcCrypto.decrypt_confirmation(self._session_key, encrypted)
+        if plaintext != CONFIRM_CENTRAL:
+            raise ValueError("Central confirmation mismatch")
+
+        encrypted_confirm = BlerpcCrypto.encrypt_confirmation(
+            self._session_key, CONFIRM_PERIPHERAL
+        )
+        step4 = BlerpcCrypto.build_step4_payload(encrypted_confirm)
+        session = BlerpcCryptoSession(self._session_key, is_central=False)
+
+        return step4, session
+
+    def handle_step(self, payload: bytes) -> tuple[bytes, BlerpcCryptoSession | None]:
+        """Dispatch a key exchange payload by step byte.
+
+        Returns (response_payload, session_or_none).
+        Session is returned only after step 3 completes successfully.
+
+        Raises:
+            ValueError: If the step byte is invalid or processing fails.
+        """
+        if len(payload) < 1:
+            raise ValueError("Empty key exchange payload")
+
+        step = payload[0]
+        if step == KEY_EXCHANGE_STEP1:
+            if self._state != 0:
+                raise RuntimeError("Invalid state for step 1")
+            return self.process_step1(payload), None
+        elif step == KEY_EXCHANGE_STEP3:
+            if self._state != 1:
+                raise RuntimeError("Invalid state for step 3")
+            step4, session = self.process_step3(payload)
+            return step4, session
+        else:
+            raise ValueError(f"Invalid key exchange step: 0x{step:02x}")
+
+    def reset(self) -> None:
+        """Reset key exchange state for new connection."""
+        self._state = 0
+        self._session_key = None
+
+
+class KnownKeyStore(Protocol):
+    """TOFU (Trust On First Use) store for peripheral Ed25519 identity keys.
+
+    The E2E handshake signature binds only the ephemeral X25519 keys, not the
+    peripheral's long-term identity key, so MitM resistance depends on the
+    central pinning that identity. Implementations supply platform-appropriate
+    persistence (file, keyring, …); this library owns the pinning policy and
+    logic (:func:`tofu_verify`).
+    """
+
+    def get(self, device_id: str) -> str | None:
+        """Return the stored hex-encoded Ed25519 public key, or None if unknown."""
+        ...
+
+    def put(self, device_id: str, hex_ed25519_pubkey: str) -> None:
+        """Persist the hex-encoded Ed25519 public key for ``device_id``."""
+        ...
+
+
+def tofu_verify(store: KnownKeyStore, device_id: str, ed25519_pubkey: bytes) -> bool:
+    """Verify a peripheral identity (TOFU) against ``store``.
+
+    Trust (and pin) the key on first use; reject a key that differs from the
+    pinned one on later connections.
+    """
+    hex_key = ed25519_pubkey.hex()
+    stored = store.get(device_id)
+    if stored is None:
+        store.put(device_id, hex_key)
+        return True
+    return stored == hex_key
+
+
+async def central_perform_key_exchange(
+    send: Callable[[bytes], Awaitable[None]],
+    receive: Callable[[], Awaitable[bytes]],
+    known_keys: KnownKeyStore | None = None,
+    device_id: str | None = None,
+    pin_identity: bool = True,
+    verify_key_cb: Callable[[bytes], bool] | None = None,
+) -> BlerpcCryptoSession:
+    """Perform the 4-step central key exchange using send/receive callbacks.
+
+    Identity pinning is **on by default** (fail-closed): pass ``known_keys`` and
+    ``device_id`` to pin the peripheral's Ed25519 identity (TOFU), or set
+    ``pin_identity`` to False to opt out (encrypted but NOT authenticated).
+    ``verify_key_cb`` is an escape hatch for custom verification and takes
+    precedence when provided.
+
+    Args:
+        send: Async callback to send a key exchange payload.
+        receive: Async callback to receive a key exchange payload.
+        known_keys: TOFU store to pin the peripheral identity against.
+        device_id: Stable identifier of the peripheral, used as the pin key.
+        pin_identity: Pin the peripheral identity (default True).
+        verify_key_cb: Optional custom verification callback (takes precedence).
+
+    Returns:
+        An established BlerpcCryptoSession.
+
+    Raises:
+        ValueError: If any step fails, or if pinning is on (the default) but no
+            ``known_keys``/``device_id`` and no ``verify_key_cb`` were supplied.
+    """
+    effective_verify_cb: Callable[[bytes], bool] | None = None
+    if verify_key_cb is not None:
+        effective_verify_cb = verify_key_cb
+    elif pin_identity:
+        if known_keys is None or device_id is None:
+            raise ValueError(
+                "Identity pinning is on by default but no KnownKeyStore/device_id "
+                "was provided. Pass known_keys and device_id to pin the peripheral "
+                "identity (TOFU), or set pin_identity=False to opt out (encrypted "
+                "but unauthenticated)."
+            )
+        store = known_keys
+        dev_id = device_id
+
+        def _tofu_cb(pub: bytes) -> bool:
+            return tofu_verify(store, dev_id, pub)
+
+        effective_verify_cb = _tofu_cb
+
+    kx = CentralKeyExchange()
+
+    # Step 1: Send central's ephemeral public key
+    step1 = kx.start()
+    await send(step1)
+
+    # Step 2: Receive peripheral's response
+    step2 = await receive()
+
+    # Step 2 -> Step 3: Verify and produce confirmation
+    step3 = kx.process_step2(step2, verify_key_cb=effective_verify_cb)
+    await send(step3)
+
+    # Step 4: Receive peripheral's confirmation
+    step4 = await receive()
+
+    return kx.finish(step4)

blerpc_protocol-0.8.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: blerpc-protocol
+Version: 0.8.0
+Summary: Container and command protocol layers for BLE RPC
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/tdaira/blerpc-protocol
+Project-URL: Repository, https://github.com/tdaira/blerpc-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0
+Dynamic: license-file
+
+# blerpc-protocol
+
+BLE RPC protocol library for Python and C.
+
+Part of the [bleRPC](https://blerpc.net) project.
+
+## Overview
+
+Python and C implementation of the bleRPC binary protocol:
+
+- Container fragmentation and reassembly with MTU-aware splitting
+- Command packet encoding/decoding with protobuf payload support
+- Control messages (timeout, stream end, capabilities, error)
+- **Encryption layer** — E2E encryption with X25519 key exchange, Ed25519 signatures, and AES-128-GCM
+
+The Python and C implementations are fully compatible and share the same wire format.
+
+## Installation
+
+```
+pip install blerpc-protocol
+```
+
+## Usage
+
+```python
+from blerpc_protocol import ContainerSplitter, ContainerAssembler, CommandPacket, CommandType
+
+# Encode a command
+packet = CommandPacket(CommandType.REQUEST, "Echo", protobuf_bytes)
+payload = packet.serialize()
+
+# Split into BLE-sized containers
+splitter = ContainerSplitter(mtu=247)
+containers = splitter.split(payload)
+
+# Send containers over BLE, then reassemble on the other side
+assembler = ContainerAssembler()
+for container in received_containers:
+    result = assembler.feed(container)
+    if result is not None:
+        response = CommandPacket.deserialize(result)
+```
+
+## Encryption
+
+The library provides E2E encryption using a 4-step key exchange protocol (X25519 ECDH + Ed25519 signatures) and AES-128-GCM session encryption.
+
+```python
+from blerpc_protocol.crypto import central_perform_key_exchange, BlerpcCryptoSession
+
+# Perform key exchange (central side)
+session = await central_perform_key_exchange(send=ble_send, receive=ble_receive)
+
+# Encrypt outgoing commands
+ciphertext = session.encrypt(plaintext)
+
+# Decrypt incoming commands
+plaintext = session.decrypt(ciphertext)
+```
+
+## C Library
+
+The C implementation is a Zephyr module with zero external dependencies. Add it to your `west.yml` manifest:
+
+```yaml
+- name: blerpc-protocol
+  url: https://github.com/tdaira/blerpc-protocol
+  revision: main
+  path: modules/lib/blerpc-protocol
+```
+
+Headers are in `c/include/blerpc_protocol/`. See [container.h](c/include/blerpc_protocol/container.h), [command.h](c/include/blerpc_protocol/command.h), and [crypto.h](c/include/blerpc_protocol/crypto.h) for the API.
+
+## Requirements
+
+- Python 3.11+
+
+## License
+
+[Apache-2.0](LICENSE)

blerpc_protocol-0.8.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+blerpc_protocol/__init__.py,sha256=2BgZ1u-suenxFfjSqIalJq5LxePIo-ZjzE-NeToT-2k,1546
+blerpc_protocol/command.py,sha256=XlIvFHZE25TR-5dt3dV-SFlEJBip2CdT0tOKp4Aacos,2090
+blerpc_protocol/container.py,sha256=Km_Ew1rTUej1FNACv17bZXdq57UcruLiXP-5X8ui3vo,12640
+blerpc_protocol/crypto.py,sha256=Lbu4L14fmDUFuAtcUI0ERneUI0sCi71YdfR8ugLS8Bo,21980
+blerpc_protocol-0.8.0.dist-info/licenses/LICENSE,sha256=qHK2c7bu8O4yjPR3AF133UThcnVxM98r9uXKmM22rPA,547
+blerpc_protocol-0.8.0.dist-info/METADATA,sha256=QaV6uTctqH1gu44-5il3iRI0KWPm9ZPKbDrCULR0Up4,3100
+blerpc_protocol-0.8.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+blerpc_protocol-0.8.0.dist-info/top_level.txt,sha256=nJrJWULXoQX-r-uykVf9tklDEEPS-Jr-Y1MOVg2e8wI,16
+blerpc_protocol-0.8.0.dist-info/RECORD,,

blerpc_protocol-0.8.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

blerpc_protocol-0.8.0.dist-info/licenses/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 tdaira
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

blerpc_protocol-0.8.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+blerpc_protocol