tescmd 0.1.2__py3-none-any.whl

tescmd/protocol/session.py

@@ -0,0 +1,318 @@
+"""ECDH session management for the Vehicle Command Protocol.
+
+Manages per-(VIN, domain) ECDH sessions with in-memory caching,
+counter management, and automatic re-handshake on expiry.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import logging
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from tescmd.api.errors import (
+    KeyNotEnrolledError,
+    SessionError,
+    TeslaAPIError,
+    VehicleAsleepError,
+)
+from tescmd.crypto.ecdh import derive_session_key, get_uncompressed_public_key
+from tescmd.protocol.encoder import build_session_info_request, encode_routable_message
+from tescmd.protocol.protobuf.messages import (
+    FAULT_DESCRIPTIONS,
+    KEY_FAULTS,
+    TRANSIENT_FAULTS,
+    Domain,
+    MessageFault,
+    RoutableMessage,
+    SessionInfo,
+)
+from tescmd.protocol.signer import (
+    derive_session_info_key,
+    derive_signing_key,
+    verify_session_info_tag,
+)
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from cryptography.hazmat.primitives.asymmetric import ec
+
+    from tescmd.api.client import TeslaFleetClient
+
+# Default session TTL (5 minutes)
+_SESSION_TTL = 300
+
+# Retry config for transient handshake faults (BUSY, TIMEOUT, INTERNAL).
+# The vehicle's VCSEC subsystem needs time to boot after waking.
+_HANDSHAKE_MAX_RETRIES = 3
+_HANDSHAKE_RETRY_DELAY = 3.0  # seconds between retries
+
+
+@dataclass
+class Session:
+    """An active ECDH session with a vehicle for a specific domain."""
+
+    vin: str
+    domain: Domain
+    shared_key: bytes
+    signing_key: bytes
+    session_info_key: bytes
+    epoch: bytes
+    counter: int
+    clock_offset: int  # vehicle_clock - local_clock (seconds)
+    created_at: float
+    ttl: float = _SESSION_TTL
+
+    @property
+    def is_expired(self) -> bool:
+        return time.monotonic() - self.created_at > self.ttl
+
+    def next_counter(self) -> int:
+        """Return and increment the anti-replay counter."""
+        self.counter += 1
+        return self.counter
+
+
+class SessionManager:
+    """Manages ECDH sessions per (VIN, domain).
+
+    Usage::
+
+        mgr = SessionManager(private_key, client)
+        session = await mgr.get_session(vin, Domain.DOMAIN_INFOTAINMENT)
+        # session.signing_key, session.epoch, session.counter, ...
+    """
+
+    def __init__(
+        self,
+        private_key: ec.EllipticCurvePrivateKey,
+        client: TeslaFleetClient,
+    ) -> None:
+        self._private_key = private_key
+        self._client = client
+        self._client_public_key = get_uncompressed_public_key(private_key)
+        self._sessions: dict[tuple[str, Domain], Session] = {}
+
+    @property
+    def client_public_key(self) -> bytes:
+        return self._client_public_key
+
+    async def get_session(self, vin: str, domain: Domain) -> Session:
+        """Return a valid session, performing a handshake if needed."""
+        key = (vin, domain)
+        session = self._sessions.get(key)
+        if session is not None and not session.is_expired:
+            return session
+
+        session = await self._handshake(vin, domain)
+        self._sessions[key] = session
+        return session
+
+    def invalidate(self, vin: str, domain: Domain | None = None) -> None:
+        """Invalidate cached sessions for a VIN (optionally for a specific domain)."""
+        if domain is not None:
+            self._sessions.pop((vin, domain), None)
+        else:
+            for key in list(self._sessions):
+                if key[0] == vin:
+                    del self._sessions[key]
+
+    async def _handshake(self, vin: str, domain: Domain) -> Session:
+        """Perform ECDH handshake with the vehicle.
+
+        1. Build RoutableMessage with session_info_request
+        2. POST to /api/1/vehicles/{vin}/signed_command
+        3. Check for fault codes — retry transient faults (BUSY/TIMEOUT/INTERNAL)
+        4. Parse vehicle's SessionInfo response
+        5. ECDH → derive shared key
+        6. Validate response HMAC
+        7. Store session
+        """
+        last_fault: MessageFault | None = None
+
+        for attempt in range(1, _HANDSHAKE_MAX_RETRIES + 1):
+            # HTTP 408 from the signed_command endpoint means the vehicle's
+            # subsystem (VCSEC/Infotainment) didn't respond within the API
+            # server's timeout window — NOT necessarily that the vehicle is
+            # asleep.  Retry it like a transient protobuf fault.
+            try:
+                response_msg = await self._send_handshake(vin, domain)
+            except VehicleAsleepError:
+                if attempt < _HANDSHAKE_MAX_RETRIES:
+                    logger.debug(
+                        "Handshake HTTP 408 for %s (%s), retry %d/%d",
+                        vin,
+                        domain.name,
+                        attempt,
+                        _HANDSHAKE_MAX_RETRIES,
+                    )
+                    await asyncio.sleep(_HANDSHAKE_RETRY_DELAY)
+                    continue
+                # Exhausted retries — re-raise so auto_wake() can handle
+                # genuinely asleep vehicles.
+                raise
+
+            # Check for vehicle-side fault before looking at session_info.
+            fault = response_msg.signed_message_fault
+            logger.debug(
+                "Handshake parsed for %s (%s): fault=%s, has_session_info=%s, "
+                "has_protobuf_msg=%s, has_signature=%s",
+                vin,
+                domain.name,
+                fault.name,
+                bool(response_msg.session_info),
+                bool(response_msg.protobuf_message_as_bytes),
+                response_msg.signature_data is not None,
+            )
+            if fault != MessageFault.ERROR_NONE:
+                desc = FAULT_DESCRIPTIONS.get(fault, fault.name)
+                last_fault = fault
+
+                # Key not recognized → permanent error, don't retry.
+                if fault in KEY_FAULTS:
+                    raise KeyNotEnrolledError(
+                        f"Vehicle rejected handshake: {desc}",
+                        status_code=422,
+                    )
+
+                # Transient fault → retry after delay.
+                if fault in TRANSIENT_FAULTS and attempt < _HANDSHAKE_MAX_RETRIES:
+                    logger.debug(
+                        "Handshake fault %s for %s (%s), retry %d/%d",
+                        fault.name,
+                        vin,
+                        domain.name,
+                        attempt,
+                        _HANDSHAKE_MAX_RETRIES,
+                    )
+                    await asyncio.sleep(_HANDSHAKE_RETRY_DELAY)
+                    continue
+
+                # Non-transient or exhausted retries.
+                raise SessionError(f"Vehicle rejected handshake for {vin} ({domain.name}): {desc}")
+
+            if not response_msg.session_info:
+                raise SessionError(
+                    f"No session_info in handshake response for {vin} ({domain.name})"
+                )
+
+            return self._build_session(vin, domain, response_msg)
+
+        # Should not be reached, but handle exhausted retries with last fault.
+        desc = FAULT_DESCRIPTIONS.get(last_fault, str(last_fault)) if last_fault else "unknown"
+        raise SessionError(
+            f"Handshake failed after {_HANDSHAKE_MAX_RETRIES} attempts "
+            f"for {vin} ({domain.name}): {desc}"
+        )
+
+    async def _send_handshake(self, vin: str, domain: Domain) -> RoutableMessage:
+        """Send a session_info_request and return the parsed response."""
+        request_msg = build_session_info_request(
+            domain=domain,
+            client_public_key=self._client_public_key,
+        )
+        encoded = encode_routable_message(request_msg)
+        logger.debug(
+            "Sending handshake for %s (%s): %d bytes encoded, pub_key=%d bytes",
+            vin,
+            domain.name,
+            len(encoded),
+            len(self._client_public_key),
+        )
+
+        try:
+            response_data = await self._client.post(
+                f"/api/1/vehicles/{vin}/signed_command",
+                json={"routable_message": encoded},
+            )
+        except TeslaAPIError:
+            # Let domain-specific errors (VehicleAsleepError, RateLimitError,
+            # etc.) propagate so callers like auto_wake() can handle them.
+            raise
+        except Exception as exc:
+            raise SessionError(
+                f"Session handshake failed for {vin} ({domain.name}): {exc}"
+            ) from exc
+
+        response_b64: str = response_data.get("response", "")
+        if not response_b64:
+            logger.debug(
+                "Empty handshake response for %s (%s): %r",
+                vin,
+                domain.name,
+                response_data,
+            )
+            raise SessionError(f"Empty session handshake response for {vin} ({domain.name})")
+
+        try:
+            response_bytes = base64.b64decode(response_b64)
+        except Exception as exc:
+            raise SessionError(f"Failed to decode handshake response: {exc}") from exc
+
+        logger.debug(
+            "Handshake response for %s (%s): %d bytes, hex=%s",
+            vin,
+            domain.name,
+            len(response_bytes),
+            response_bytes.hex(),
+        )
+
+        try:
+            return RoutableMessage.parse(response_bytes)
+        except Exception as exc:
+            raise SessionError(f"Failed to parse handshake response: {exc}") from exc
+
+    def _build_session(self, vin: str, domain: Domain, response_msg: RoutableMessage) -> Session:
+        """Derive keys and build a Session from a successful handshake response."""
+        session_info = SessionInfo.parse(response_msg.session_info)
+        if not session_info.public_key:
+            raise SessionError(f"No vehicle public key in session info for {vin} ({domain.name})")
+
+        # ECDH key derivation
+        try:
+            shared_key = derive_session_key(self._private_key, session_info.public_key)
+        except Exception as exc:
+            raise SessionError(
+                f"ECDH key derivation failed for {vin} ({domain.name}): {exc}"
+            ) from exc
+
+        # Derive sub-keys
+        signing_key = derive_signing_key(shared_key)
+        session_info_key = derive_session_info_key(shared_key)
+
+        # Verify session info HMAC tag (if present in response)
+        sig = response_msg.signature_data
+        si_tag = sig.session_info_tag if sig else None
+        if (
+            si_tag
+            and si_tag.tag
+            and not verify_session_info_tag(
+                session_info_key,
+                response_msg.session_info,
+                si_tag.tag,
+            )
+        ):
+            raise SessionError(
+                f"Session info HMAC verification failed for {vin} ({domain.name}). "
+                "The vehicle response may have been tampered with."
+            )
+
+        # Calculate clock offset
+        local_time = int(time.time())
+        clock_offset = session_info.clock_time - local_time if session_info.clock_time else 0
+
+        return Session(
+            vin=vin,
+            domain=domain,
+            shared_key=shared_key,
+            signing_key=signing_key,
+            session_info_key=session_info_key,
+            epoch=session_info.epoch,
+            counter=session_info.counter,
+            clock_offset=clock_offset,
+            created_at=time.monotonic(),
+        )

tescmd/protocol/signer.py

@@ -0,0 +1,84 @@
+"""HMAC-SHA256 command signing for the Vehicle Command Protocol.
+
+Signing flow (for the REST/Fleet API path):
+
+1. Serialize metadata as TLV: ``encode_metadata(epoch, expires_at, counter)``
+2. Derive signing key: ``K' = HMAC-SHA256(K, b"authenticated command")``
+3. Compute tag: ``HMAC-SHA256(K', metadata_bytes || 0xFF || payload_bytes)``
+4. For VCSEC domain: truncate tag to 17 bytes.
+5. Attach to ``RoutableMessage.signature_data.HMAC_PersonalizedData.tag``
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from tescmd.protocol.protobuf.messages import Domain
+
+# Derivation labels (from Tesla vehicle-command specification)
+_LABEL_AUTHENTICATED_COMMAND = b"authenticated command"
+_LABEL_SESSION_INFO = b"session info"
+
+# VCSEC domain uses a truncated 17-byte tag
+_VCSEC_TAG_LENGTH = 17
+
+
+def derive_signing_key(session_key: bytes) -> bytes:
+    """Derive the command signing key: ``HMAC-SHA256(K, "authenticated command")``."""
+    return hmac.new(session_key, _LABEL_AUTHENTICATED_COMMAND, hashlib.sha256).digest()
+
+
+def derive_session_info_key(session_key: bytes) -> bytes:
+    """Derive the session info verification key: ``HMAC-SHA256(K, "session info")``."""
+    return hmac.new(session_key, _LABEL_SESSION_INFO, hashlib.sha256).digest()
+
+
+def compute_hmac_tag(
+    signing_key: bytes,
+    metadata_bytes: bytes,
+    payload_bytes: bytes,
+    *,
+    domain: Domain = Domain.DOMAIN_INFOTAINMENT,
+) -> bytes:
+    """Compute the HMAC-SHA256 authentication tag.
+
+    Parameters
+    ----------
+    signing_key:
+        The derived signing key from :func:`derive_signing_key`.
+    metadata_bytes:
+        TLV-encoded metadata (epoch, expires_at, counter, flags).
+    payload_bytes:
+        The serialized protobuf command payload.
+    domain:
+        The routing domain — VCSEC tags are truncated to 17 bytes.
+
+    Returns
+    -------
+    bytes
+        The HMAC tag (32 bytes for Infotainment, 17 bytes for VCSEC).
+    """
+    # The Go SDK streams metadata entries into the hash, then Checksum()
+    # writes a bare TAG_END byte (0xFF) before the payload — no length byte.
+    #   m.Context.Write([]byte{byte(signatures.Tag_TAG_END)})  // just 0xFF
+    #   m.Context.Write(message)
+    msg = metadata_bytes + b"\xff" + payload_bytes
+    tag = hmac.new(signing_key, msg, hashlib.sha256).digest()
+
+    if domain == Domain.DOMAIN_VEHICLE_SECURITY:
+        return tag[:_VCSEC_TAG_LENGTH]
+    return tag
+
+
+def verify_session_info_tag(
+    session_info_key: bytes,
+    session_info_bytes: bytes,
+    expected_tag: bytes,
+) -> bool:
+    """Verify the HMAC tag on a SessionInfo response.
+
+    Returns True if the tag is valid.
+    """
+    computed = hmac.new(session_info_key, session_info_bytes, hashlib.sha256).digest()
+    return hmac.compare_digest(computed, expected_tag)