python-can-hub 0.2.2__py3-none-win_amd64.whl

canhub/__init__.py

@@ -0,0 +1,16 @@
+"""python-can-hub: native python-can backend for can-hub.
+
+The native library loads lazily: importing the package (e.g. for the pure
+python fingerprint helper) must work without libcanhub present.
+"""
+
+from .fingerprint import identity_fingerprint
+
+__all__ = ["CanHubBus", "identity_fingerprint"]
+
+
+def __getattr__(name):
+    if name == "CanHubBus":
+        from .bus import CanHubBus
+        return CanHubBus
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

canhub/__main__.py

@@ -0,0 +1,18 @@
+"""usage: python3 -m canhub fingerprint <certificate.pem>"""
+
+import sys
+
+from .fingerprint import identity_fingerprint
+
+
+def main() -> int:
+    if len(sys.argv) != 3 or sys.argv[1] != "fingerprint":
+        print(__doc__, file=sys.stderr)
+        return 1
+
+    print(identity_fingerprint(sys.argv[2]))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

canhub/_native.py

@@ -0,0 +1,128 @@
+"""ctypes bindings over the libcanhub C ABI (include/canhub.h, version 1).
+
+The shared library is resolved in order: the CANHUB_LIBRARY environment
+variable, the copy bundled inside this package, the system library path.
+"""
+
+import ctypes
+import os
+import sys
+from ctypes import POINTER, Structure, c_char, c_char_p, c_int32, c_size_t, c_uint8, c_uint32, c_uint64, c_void_p
+
+FRAME_PAYLOAD_MAX = 64
+AGENT_NAME_MAX = 128
+INTERFACE_NAME_MAX = 16
+FILTERS_MAX = 16
+
+CAN_ID_MASK = 0x1FFFFFFF
+CAN_ID_FLAG_ERR = 1 << 29
+CAN_ID_FLAG_RTR = 1 << 30
+CAN_ID_FLAG_EFF = 1 << 31
+
+FRAME_FLAG_FD = 1 << 0
+FRAME_FLAG_BRS = 1 << 1
+
+OPEN_FLAG_NO_ECHO = 1 << 0
+OPEN_FLAG_WRITE = 1 << 1
+
+OK = 0
+RECEIVED = 1
+ERR_TIMEOUT = -1
+ERR_DISCONNECTED = -2
+ERR_NOT_FOUND = -3
+ERR_OPEN_REJECTED = -4
+ERR_WRITE_DENIED = -5
+ERR_READ_DENIED = -6
+ERR_ARGUMENT = -7
+ERR_STATE = -8
+ERR_TRANSPORT = -9
+ERR_HUB = -10
+
+
+class CanHubFrame(Structure):
+    _fields_ = [
+        ("timestamp_us", c_uint64),
+        ("can_id", c_uint32),
+        ("flags", c_uint8),
+        ("length", c_uint8),
+        ("reserved", c_uint8 * 2),
+        ("payload", c_uint8 * FRAME_PAYLOAD_MAX),
+    ]
+
+
+class CanHubInterfaceInfo(Structure):
+    _fields_ = [
+        ("interface_id", c_uint32),
+        ("agent", c_char * AGENT_NAME_MAX),
+        ("interface_name", c_char * INTERFACE_NAME_MAX),
+    ]
+
+
+class CanHubFilter(Structure):
+    _fields_ = [
+        ("can_id", c_uint32),
+        ("can_mask", c_uint32),
+    ]
+
+
+class CanHubConnectConfig(Structure):
+    _fields_ = [
+        ("struct_size", c_uint32),
+        ("url", c_char_p),
+        ("state_directory", c_char_p),
+        ("certificate_path", c_char_p),
+        ("key_path", c_char_p),
+        ("hub_fingerprint", c_char_p),
+        ("connect_timeout_ms", c_int32),
+    ]
+
+
+def _load_library():
+    bundled_name = "libcanhub.dll" if sys.platform == "win32" else "libcanhub.so"
+
+    override = os.environ.get("CANHUB_LIBRARY")
+    if override:
+        return ctypes.CDLL(override)
+
+    bundled = os.path.join(os.path.dirname(__file__), bundled_name)
+    if os.path.exists(bundled):
+        return ctypes.CDLL(bundled)
+
+    if sys.platform == "win32":
+        return ctypes.CDLL("libcanhub.dll")
+    return ctypes.CDLL("libcanhub.so.0")
+
+
+lib = _load_library()
+
+lib.canhub_api_version.restype = c_uint32
+lib.canhub_api_version.argtypes = []
+
+lib.canhub_connect.restype = c_void_p
+lib.canhub_connect.argtypes = [POINTER(CanHubConnectConfig)]
+
+lib.canhub_close.restype = None
+lib.canhub_close.argtypes = [c_void_p]
+
+lib.canhub_last_error.restype = c_char_p
+lib.canhub_last_error.argtypes = [c_void_p]
+
+lib.canhub_list.restype = c_int32
+lib.canhub_list.argtypes = [c_void_p, POINTER(CanHubInterfaceInfo), c_size_t, c_int32]
+
+lib.canhub_open.restype = c_int32
+lib.canhub_open.argtypes = [c_void_p, c_char_p, c_uint32, c_int32]
+
+lib.canhub_set_filters.restype = c_int32
+lib.canhub_set_filters.argtypes = [c_void_p, POINTER(CanHubFilter), c_uint8]
+
+lib.canhub_recv.restype = c_int32
+lib.canhub_recv.argtypes = [c_void_p, POINTER(CanHubFrame), c_int32]
+
+lib.canhub_send.restype = c_int32
+lib.canhub_send.argtypes = [c_void_p, POINTER(CanHubFrame)]
+
+
+def last_error(session):
+    detail = lib.canhub_last_error(session)
+    return detail.decode("utf-8", errors="replace") if detail else "unknown error"

canhub/bus.py

@@ -0,0 +1,166 @@
+"""python-can backend over libcanhub: can.Bus(interface="canhub", ...)."""
+
+import ctypes
+from typing import Optional, Tuple
+
+from can import BusABC, CanInitializationError, CanOperationError, Message
+
+from . import _native as native
+
+DEFAULT_TIMEOUT_MS = 5000
+FINGERPRINT_HEX_LENGTH = 64
+
+
+def _is_fingerprint(text: str) -> bool:
+    if len(text) != FINGERPRINT_HEX_LENGTH:
+        return False
+    return all(character in "0123456789abcdef" for character in text.lower())
+
+
+class CanHubBus(BusABC):
+    """One hub interface as a python-can bus.
+
+    :param channel: namespaced interface name ``agent/iface`` or numeric id.
+    :param url: hub url (``quic://host:port``, ``tls://``, ``tcp://``,
+        ``unix:///path``); ``None`` connects to the local hub unix socket.
+    :param identity_cert: path to the client certificate (PEM). Together
+        with ``identity_key`` it injects an explicit identity (the
+        fingerprint the hub ACLs refer to) instead of the state dir one.
+    :param identity_key: path to the client private key (PEM).
+    :param hub_fingerprint: expected hub fingerprint (64 hex). When given,
+        the connection is rejected unless the hub presents exactly this
+        certificate — no TOFU, no pin store on disk.
+    :param state_dir: directory holding the client TLS identity and the
+        TOFU pin store (tls/quic only); ``None`` uses the can-hub default.
+    :param receive_own_messages: also receive the frames this bus sends.
+    """
+
+    def __init__(
+        self,
+        channel: str,
+        url: Optional[str] = None,
+        identity_cert: Optional[str] = None,
+        identity_key: Optional[str] = None,
+        hub_fingerprint: Optional[str] = None,
+        state_dir: Optional[str] = None,
+        receive_own_messages: bool = False,
+        **kwargs,
+    ):
+        self._session = None
+        self._writable = False
+
+        if hub_fingerprint is not None:
+            hub_fingerprint = str(hub_fingerprint)
+            if not _is_fingerprint(hub_fingerprint):
+                raise CanInitializationError(
+                    "hub_fingerprint must be 64 hex characters (it may have been "
+                    "mangled by python-can config value casting; pass it as a string)"
+                )
+
+        config = native.CanHubConnectConfig()
+        config.struct_size = ctypes.sizeof(config)
+        config.url = url.encode() if url else None
+        config.state_directory = state_dir.encode() if state_dir else None
+        config.certificate_path = identity_cert.encode() if identity_cert else None
+        config.key_path = identity_key.encode() if identity_key else None
+        config.hub_fingerprint = hub_fingerprint.encode() if hub_fingerprint else None
+        config.connect_timeout_ms = DEFAULT_TIMEOUT_MS
+
+        self._session = native.lib.canhub_connect(ctypes.byref(config))
+        if not self._session:
+            raise CanInitializationError(f"could not connect to {url or 'the local can-hub socket'}")
+
+        self._open(str(channel), receive_own_messages)
+        self.channel_info = f"canhub {channel} via {url or 'unix socket'}"
+        super().__init__(channel=channel, **kwargs)
+
+    def _recv_internal(self, timeout: Optional[float]) -> Tuple[Optional[Message], bool]:
+        frame = native.CanHubFrame()
+        timeout_ms = -1 if timeout is None else max(0, int(timeout * 1000))
+
+        result = native.lib.canhub_recv(self._session, ctypes.byref(frame), timeout_ms)
+        if result == native.RECEIVED:
+            return self._to_message(frame), self._filters_applied
+        if result == native.ERR_TIMEOUT:
+            return None, self._filters_applied
+
+        raise CanOperationError(native.last_error(self._session))
+
+    def send(self, msg: Message, timeout: Optional[float] = None) -> None:
+        frame = native.CanHubFrame()
+
+        if not self._writable:
+            raise CanOperationError("bus is read-only (write denied by the hub ACL)")
+        if msg.timestamp:
+            frame.timestamp_us = int(msg.timestamp * 1_000_000)
+        frame.can_id = msg.arbitration_id & native.CAN_ID_MASK
+        if msg.is_extended_id:
+            frame.can_id |= native.CAN_ID_FLAG_EFF
+        if msg.is_remote_frame:
+            frame.can_id |= native.CAN_ID_FLAG_RTR
+        if msg.is_error_frame:
+            frame.can_id |= native.CAN_ID_FLAG_ERR
+        if msg.is_fd:
+            frame.flags |= native.FRAME_FLAG_FD
+        if msg.bitrate_switch:
+            frame.flags |= native.FRAME_FLAG_BRS
+        data = bytes(msg.data or b"")
+        frame.length = len(data)
+        frame.payload[: len(data)] = data
+
+        result = native.lib.canhub_send(self._session, ctypes.byref(frame))
+        if result != native.OK:
+            raise CanOperationError(native.last_error(self._session))
+
+    def shutdown(self) -> None:
+        super().shutdown()
+        if self._session:
+            native.lib.canhub_close(self._session)
+            self._session = None
+
+    @property
+    def _filters_applied(self) -> bool:
+        return getattr(self, "_hardware_filtered", False)
+
+    def _apply_filters(self, filters) -> None:
+        if not filters or len(filters) > native.FILTERS_MAX:
+            self._hardware_filtered = False
+            return
+
+        native_filters = (native.CanHubFilter * len(filters))()
+        for slot, can_filter in zip(native_filters, filters):
+            slot.can_id = can_filter["can_id"]
+            slot.can_mask = can_filter["can_mask"]
+        result = native.lib.canhub_set_filters(self._session, native_filters, len(filters))
+        self._hardware_filtered = result == native.OK
+
+    def _open(self, channel: str, receive_own_messages: bool) -> None:
+        flags = native.OPEN_FLAG_WRITE
+        if not receive_own_messages:
+            flags |= native.OPEN_FLAG_NO_ECHO
+
+        result = native.lib.canhub_open(self._session, channel.encode(), flags, DEFAULT_TIMEOUT_MS)
+        if result == native.ERR_WRITE_DENIED:
+            result = native.lib.canhub_open(self._session, channel.encode(), flags & ~native.OPEN_FLAG_WRITE, DEFAULT_TIMEOUT_MS)
+        else:
+            self._writable = result == native.OK
+
+        if result != native.OK:
+            detail = native.last_error(self._session)
+            native.lib.canhub_close(self._session)
+            self._session = None
+            raise CanInitializationError(f"could not open {channel}: {detail}")
+
+    @staticmethod
+    def _to_message(frame: native.CanHubFrame) -> Message:
+        return Message(
+            timestamp=frame.timestamp_us / 1_000_000,
+            arbitration_id=frame.can_id & native.CAN_ID_MASK,
+            is_extended_id=bool(frame.can_id & native.CAN_ID_FLAG_EFF),
+            is_remote_frame=bool(frame.can_id & native.CAN_ID_FLAG_RTR),
+            is_error_frame=bool(frame.can_id & native.CAN_ID_FLAG_ERR),
+            is_fd=bool(frame.flags & native.FRAME_FLAG_FD),
+            bitrate_switch=bool(frame.flags & native.FRAME_FLAG_BRS),
+            dlc=frame.length,
+            data=bytes(frame.payload[: frame.length]),
+        )

canhub/fingerprint.py

@@ -0,0 +1,23 @@
+"""can-hub fingerprints without native code: sha256 over the certificate DER."""
+
+import base64
+import hashlib
+import re
+
+_PEM_BODY = re.compile(
+    r"-----BEGIN CERTIFICATE-----(.*?)-----END CERTIFICATE-----",
+    re.DOTALL,
+)
+
+
+def identity_fingerprint(certificate_path: str) -> str:
+    """Fingerprint of a PEM certificate: what the hub pins and the ACLs key on."""
+    with open(certificate_path, "r", encoding="ascii") as certificate_file:
+        pem = certificate_file.read()
+
+    match = _PEM_BODY.search(pem)
+    if match is None:
+        raise ValueError(f"{certificate_path} does not contain a PEM certificate")
+
+    der = base64.b64decode(match.group(1))
+    return hashlib.sha256(der).hexdigest()

python_can_hub-0.2.2.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.1
+Name: python-can-hub
+Version: 0.2.2
+Summary: python-can backend for can-hub: remote CAN interfaces over unix/tcp/tls/quic
+License: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/can-hub-io/can-hub
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: python-can >=4.0
+
+# python-can-hub
+
+Native [python-can](https://python-can.readthedocs.io) backend for
+[can-hub](https://github.com/can-hub-io/can-hub): consume remote CAN interfaces
+exported by can-hub agents, directly over the binary protocol — unix socket,
+plain TCP, TLS or QUIC, with mTLS identity and TOFU pinning on the encrypted
+transports. No bridge process in between.
+
+```python
+import can
+
+bus = can.Bus(
+    interface="canhub",
+    channel="truck42/can0",
+    url="quic://hub.example.com:7227",
+)
+bus.send(can.Message(arbitration_id=0x123, data=b"\xDE\xAD\xBE\xEF"))
+for message in bus:
+    print(message)
+```
+
+- `channel`: namespaced interface `agent/iface` (or the numeric id from
+  `can-hub-client list`).
+- `url`: omit to connect to the local hub unix socket.
+- `state_dir`: client TLS identity + pin store location (tls/quic).
+- `receive_own_messages`: standard python-can echo semantics.
+
+Write access follows the hub client ACLs: if the ACL grants read-only, the
+bus opens read-only and `send()` raises.
+
+The wheel bundles `libcanhub.so` with the TLS/QUIC stack linked in
+statically; the only runtime dependency is glibc.
+
+## Building from source
+
+```sh
+./scripts/build-python-wheel.sh        # host arch, glibc-tagged (local dev)
+pip install python/dist/*.whl
+```
+
+Distributable manylinux wheels are built per architecture in a manylinux
+container and repaired by auditwheel (needs docker, plus QEMU binfmt for the
+cross arches):
+
+```sh
+./scripts/build-python-wheel.sh x86_64   # python/dist/x86_64/*.whl
+./scripts/build-python-wheel.sh aarch64
+./scripts/build-python-wheel.sh armv7l
+```
+
+The release workflow builds all three and publishes them to PyPI on a `v*`
+tag.

python_can_hub-0.2.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+canhub/__init__.py,sha256=yC7SFSz4vUDFgve7gehAaOSqZ1Iv1Kbv1A4c5nj_XcM,485
+canhub/__main__.py,sha256=WM0VMTSjzySENh7zkbTT4WpLnqyS_gsZBgJ4f05qNHQ,366
+canhub/_native.py,sha256=4MHqnxR86NfMN_4jrp5rg60MR1hfhD7p-zXozSoAEAg,3295
+canhub/bus.py,sha256=dLwIGXdGplCyG_vh0Rb9DmM5kUjGCMyV_OlMU10q4x4,7060
+canhub/fingerprint.py,sha256=N38dP3_odFYn6821XViWG6aQKUPhxJHDY8xE8uW8zNo,711
+canhub/libcanhub.dll,sha256=BFcvsPyRdRgD2wiGAAlHZEDRXTqHQlHwjlTkDaxu19k,6396928
+python_can_hub-0.2.2.dist-info/METADATA,sha256=MaxFh9oRfrcQ60f7_UfbYdbz6Ng3RarPS0Om8fDaWVs,1998
+python_can_hub-0.2.2.dist-info/WHEEL,sha256=KTdQDMVZqs2eeRhOpF4kInPW2OgLgRWl7KhVZQueA2o,99
+python_can_hub-0.2.2.dist-info/entry_points.txt,sha256=ZfPo9cCR4xH9BjYRCi_nOcw_48SN6vqboV0B2y8HcjU,46
+python_can_hub-0.2.2.dist-info/top_level.txt,sha256=nPyUT2Mw-NsKrJhpH-4EUcBBqz7GOSwfxnGkFEILnKk,7
+python_can_hub-0.2.2.dist-info/RECORD,,

python_can_hub-0.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.42.0)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64
+

python_can_hub-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[can.interface]
+canhub = canhub.bus:CanHubBus

python_can_hub-0.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+canhub