keylet 0.1.0__tar.gz

keylet-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.3
+Name: keylet
+Version: 0.1.0
+Summary: Client application Tillitis TKey ML-DSA signer
+Author: Jussi Kukkonen
+Author-email: Jussi Kukkonen <jkukkonen@google.com>
+Requires-Dist: cryptography>=48.0.0
+Requires-Dist: pyserial>=3.5
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+## Keylet -- Client library for Tillitis TKey
+
+This library provides a client implementation for the Tillitis TKey, and specifically
+the [tkey-pq-device-signer](https://github.com/tillitis/tkey-pq-device-signer) application.

keylet-0.1.0/README.md

@@ -0,0 +1,4 @@
+## Keylet -- Client library for Tillitis TKey
+
+This library provides a client implementation for the Tillitis TKey, and specifically
+the [tkey-pq-device-signer](https://github.com/tillitis/tkey-pq-device-signer) application.

keylet-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "keylet"
+version = "0.1.0"
+description = "Client application Tillitis TKey ML-DSA signer"
+readme = "README.md"
+authors = [
+    { name = "Jussi Kukkonen", email = "jkukkonen@google.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography>=48.0.0",
+    "pyserial>=3.5",
+]
+
+[project.scripts]
+keylet = "keylet.bin.cli:main"
+
+
+[dependency-groups]
+dev = [
+    "mypy>=1.10.0",
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.3.0",
+    "types-pyserial>=3.5.0.20240310",
+    "zizmor>=0.8.0",
+    "zensical>=0.0.46",
+    "mkdocstrings[python]>=1.0.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.23,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "UP",   # pyupgrade
+    "RUF",  # Ruff-specific rules
+]
+ignore = []
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = "serial.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+markers = [
+    "device: tests requiring a physical TKey device running a no-touch binary",
+]

keylet-0.1.0/src/keylet/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 keylet authors
+
+# ruff: noqa: F401
+from keylet.tkey_sign import SignApp, TKeySign

keylet-0.1.0/src/keylet/_serial_hack.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 keylet authors
+
+import os
+import select
+import sys
+
+if sys.platform == "linux":
+    import array
+    import fcntl
+    import termios
+
+from typing import Protocol
+
+
+class SerialConnection(Protocol):
+    timeout: float
+
+    def read(self, n: int) -> bytes: ...
+    def write(self, data: bytes) -> int: ...
+    def close(self) -> None: ...
+
+    @property
+    def in_waiting(self) -> int: ...
+
+
+class RawSerialConnection:
+    """A Linux specific raw Python serial connection.
+
+    This helper exists because pyserial does not work with glibc >=2.42:
+    https://github.com/pyserial/pyserial/commit/70d18864 is the missing bug fix.
+    """
+
+    def __init__(self, port: str, baudrate: int, timeout: float) -> None:
+        self.timeout = timeout
+        self._fd: int | None = self._open(port, baudrate)
+
+    def _open(self, port: str, baudrate: int) -> int:
+        fd = os.open(port, os.O_RDWR | os.O_NOCTTY | os.O_NONBLOCK)
+        try:
+            # 1. Use termios to configure raw 8N1 mode
+            attrs = termios.tcgetattr(fd)
+
+            # Clear input processing
+            attrs[0] &= ~(
+                termios.IGNBRK
+                | termios.BRKINT
+                | termios.PARMRK
+                | termios.ISTRIP
+                | termios.INLCR
+                | termios.IGNCR
+                | termios.ICRNL
+                | termios.IXON
+                | termios.IXOFF
+                | termios.IXANY
+                | termios.INPCK
+            )
+            # Clear output processing (raw output)
+            attrs[1] &= ~termios.OPOST
+            # Clear local modes (no echo, no signals, no canonical input)
+            attrs[3] &= ~(
+                termios.ECHO
+                | termios.ECHONL
+                | termios.ICANON
+                | termios.ISIG
+                | termios.IEXTEN
+            )
+            # Clear control modes (no size, parity, stop bits, flow control)
+            attrs[2] &= ~(
+                termios.CSIZE | termios.PARENB | termios.CSTOPB | termios.CRTSCTS
+            )
+            attrs[2] |= termios.CS8 | termios.CREAD | termios.CLOCAL
+
+            # Set speed using standard constants (this is changed below)
+            attrs[4] = termios.B9600
+            attrs[5] = termios.B9600
+
+            termios.tcsetattr(fd, termios.TCSANOW, attrs)
+
+            # 2. Use termios2 to set the custom 62500 baud rate
+            tcgets2 = 0x802C542A
+            tcsets2 = 0x402C542B
+            bother = 0o010000
+
+            buf = array.array("i", [0] * 64)
+            fcntl.ioctl(fd, tcgets2, buf)
+
+            buf[2] &= ~0x100F  # Clear CBAUD/CBAUDEX speed flags
+            buf[2] |= bother  # Flag for custom speed (BOTHER)
+            buf[9] = buf[10] = baudrate  # Set custom speed
+
+            fcntl.ioctl(fd, tcsets2, buf)
+
+            # 3. Restore blocking mode
+            flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+            fcntl.fcntl(fd, fcntl.F_SETFL, flags & ~os.O_NONBLOCK)
+
+            # 4. Acquire exclusive access
+            tiocexcl = 0x540C
+            fcntl.ioctl(fd, tiocexcl, 0)
+
+            return fd
+        except Exception:
+            os.close(fd)
+            raise
+
+    def write(self, data: bytes) -> int:
+        if self._fd is None:
+            raise ValueError("Port is closed")
+        return os.write(self._fd, data)
+
+    def read(self, n: int) -> bytes:
+        """Read exactly n bytes blockingly, respecting the configured timeout."""
+        if self._fd is None:
+            raise ValueError("Port is closed")
+        data = bytearray()
+        while len(data) < n:
+            r, _, _ = select.select([self._fd], [], [], self.timeout)
+            if not r:
+                break  # Timeout
+            chunk = os.read(self._fd, n - len(data))
+            if len(chunk) == 0:
+                break  # EOF/Disconnect
+            data.extend(chunk)
+        return bytes(data)
+
+    def reset_input_buffer(self) -> None:
+        pass
+
+    def reset_output_buffer(self) -> None:
+        pass
+
+    @property
+    def in_waiting(self) -> int:
+        if self._fd is None:
+            return 0
+        buf = array.array("i", [0])
+        try:
+            fcntl.ioctl(self._fd, termios.FIONREAD, buf)
+            return buf[0]
+        except Exception:
+            return 0
+
+    def close(self) -> None:
+        if self._fd is not None:
+            os.close(self._fd)
+            self._fd = None

keylet-0.1.0/src/keylet/bin/cli.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 keylet authors
+
+import argparse
+import sys
+from pathlib import Path
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA44PublicKey
+
+from keylet.tkey import TKeyNotFoundError
+from keylet.tkey_sign import SignApp, TKeySign
+
+
+def get_signer(device: str | None, passphrase: str | None) -> TKeySign:
+    """Helper to initialize TKeySign with the default device signer binary."""
+    app = SignApp.load_mldsa()
+    return TKeySign(app, device=device, secret=passphrase)
+
+
+def cmd_pubkey(args: argparse.Namespace) -> int:
+    try:
+        with get_signer(args.device, args.passphrase) as signer:
+            pubkey = signer.get_pubkey()
+            if args.output:
+                Path(args.output).write_bytes(pubkey)
+                print(f"Public key written to {args.output}")
+            else:
+                print(pubkey.hex())
+            return 0
+    except TKeyNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_sign(args: argparse.Namespace) -> int:
+    file_path = Path(args.file)
+    if not file_path.exists():
+        print(f"Error: File {args.file} does not exist", file=sys.stderr)
+        return 1
+
+    try:
+        data = file_path.read_bytes()
+        with get_signer(args.device, args.passphrase) as signer:
+            print("Please touch the TKey device when it flashes to sign...")
+            signature = signer.sign(data)
+
+            sig_path = file_path.with_suffix(file_path.suffix + ".signature")
+            sig_path.write_bytes(signature)
+            print(f"Signature written to {sig_path}")
+            return 0
+    except TKeyNotFoundError as e:
+        print(f"Signing failed: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    file_path = Path(args.file)
+    if not file_path.exists():
+        print(f"Error: File {args.file} does not exist", file=sys.stderr)
+        return 1
+
+    sig_path = (
+        Path(args.signature)
+        if args.signature
+        else file_path.with_suffix(file_path.suffix + ".signature")
+    )
+    if not sig_path.exists():
+        print(f"Error: Signature file {sig_path} does not exist", file=sys.stderr)
+        return 1
+
+    try:
+        file_bytes = file_path.read_bytes()
+        sig_bytes = sig_path.read_bytes()
+
+        # Get public key either from file or from device
+        if args.pubkey:
+            pubkey_bytes = Path(args.pubkey).read_bytes()
+        else:
+            print("Retrieving public key from device...")
+            with get_signer(args.device, args.passphrase) as signer:
+                pubkey_bytes = signer.get_pubkey()
+
+        # Verify signature using cryptography library
+        pubkey = MLDSA44PublicKey.from_public_bytes(pubkey_bytes)
+        pubkey.verify(sig_bytes, file_bytes)
+        print("Verification successful!")
+        return 0
+    except InvalidSignature:
+        print("Verification failed: Invalid signature", file=sys.stderr)
+        return 1
+    except TKeyNotFoundError as e:
+        print(f"Verification failed: {e}", file=sys.stderr)
+        return 1
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Tillitis TKey Keylet CLI testing tool"
+    )
+    parser.add_argument(
+        "--device", help="Serial port of the TKey device (e.g. /dev/ttyACM0)"
+    )
+    parser.add_argument("--passphrase", help="User Supplied Secret (passphrase)")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # pubkey command
+    parser_pubkey = subparsers.add_parser("pubkey", help="Get public key from device")
+    parser_pubkey.add_argument(
+        "-o", "--output", help="Output file to write public key to"
+    )
+
+    # sign command
+    parser_sign = subparsers.add_parser("sign", help="Sign a file")
+    parser_sign.add_argument("file", help="File to sign")
+
+    # verify command
+    parser_verify = subparsers.add_parser("verify", help="Verify a signature")
+    parser_verify.add_argument("file", help="File that was signed")
+    parser_verify.add_argument(
+        "--signature", help="Signature file (defaults to <FILE>.signature)"
+    )
+    parser_verify.add_argument(
+        "--pubkey", help="Public key file (retrieved from device if not specified)"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "pubkey":
+        sys.exit(cmd_pubkey(args))
+    elif args.command == "sign":
+        sys.exit(cmd_sign(args))
+    elif args.command == "verify":
+        sys.exit(cmd_verify(args))
+
+
+if __name__ == "__main__":
+    main()

keylet-0.1.0/src/keylet/resources/__init__.py

@@ -0,0 +1 @@
+# Package marker for resource files

keylet-0.1.0/src/keylet/tkey.py

@@ -0,0 +1,421 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 keylet authors
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import sys
+from dataclasses import dataclass
+from types import TracebackType
+from typing import TypeVar
+
+import serial
+from serial.tools import list_ports
+
+from keylet._serial_hack import (
+    RawSerialConnection,
+    SerialConnection,
+)
+
+logger = logging.getLogger(__name__)
+
+# USB Vendor & Product ID for TKey
+TKEY_USB_VID = 0x1207
+TKEY_USB_PID = 0x8887
+
+# Maximum size for applications to load onto TKey (100 KiB)
+APP_MAXSIZE = 100 * 1024
+
+
+# Data lengths corresponding to header length bits (0, 1, 2, 3)
+PROTO_DATA_LENGTH = [1, 4, 32, 128]
+
+
+# Length indices mapping to PROTO_DATA_LENGTH
+class LenIdx:
+    I1 = 0
+    """1-byte payload length index."""
+    I4 = 1
+    """4-byte payload length index."""
+    I32 = 2
+    """32-byte payload length index."""
+    I128 = 3
+    """128-byte payload length index."""
+
+
+@dataclass(frozen=True)
+class Rsp:
+    """Protocol response definition.
+
+    Attributes:
+        id: The response identifier byte.
+        len_idx: The length index indicating the expected data size.
+    """
+
+    id: int
+    len_idx: int
+
+
+@dataclass(frozen=True)
+class Cmd:
+    """Protocol command definition.
+
+    Attributes:
+        id: The command identifier byte.
+        endpoint: The target endpoint on the device.
+        len_idx: The length index indicating the payload data size.
+        valid_responses: A tuple of acceptable responses for this command.
+    """
+
+    id: int
+    endpoint: int
+    len_idx: int
+    valid_responses: tuple[Rsp, ...]
+
+
+class FwRsp:
+    """Firmware responses"""
+
+    NAME_VERSION = Rsp(0x02, LenIdx.I32)
+    """Response containing firmware name and version."""
+    LOAD_APP = Rsp(0x04, LenIdx.I4)
+    """Response indicating the application loading status."""
+    LOAD_APP_DATA = Rsp(0x06, LenIdx.I4)
+    """Response indicating the application data chunk status."""
+    LOAD_APP_DATA_READY = Rsp(0x07, LenIdx.I128)
+    """Response indicating all application data has been received and verified."""
+
+
+class FwCmd:
+    """Firmware commands"""
+
+    NAME_VERSION = Cmd(0x01, 2, LenIdx.I1, (FwRsp.NAME_VERSION,))
+    """Command to query the firmware name and version."""
+    LOAD_APP = Cmd(0x03, 2, LenIdx.I128, (FwRsp.LOAD_APP,))
+    """Command to initiate application loading with size and optional secret."""
+    LOAD_APP_DATA = Cmd(
+        0x05, 2, LenIdx.I128, (FwRsp.LOAD_APP_DATA, FwRsp.LOAD_APP_DATA_READY)
+    )
+    """Command to send a chunk of application binary data."""
+
+
+_TKey = TypeVar("_TKey", bound="TKey")
+
+
+class TKeyError(Exception):
+    """Base class for TKey errors."""
+
+
+class TKeyNotFoundError(TKeyError):
+    """A TKey device was not found"""
+
+
+class TKeyAppError(TKeyError):
+    """Raised when loading the application fails."""
+
+
+class TKeyIOError(TKeyError):
+    """Raised when read/write fails."""
+
+
+class TKeyProtocolError(TKeyError):
+    """Raised upon protocol errors in command or response."""
+
+
+class TKey:
+    """Base TKey Client
+
+    TKey is used to build host (client) applications for a Tillitis TKey.
+    It implements the Firmware protocol and provides serial IO as well
+    as some helpers for the actual application implementation.
+
+    Links:
+
+    * [Framing protocol](https://dev.tillitis.se/protocol/#framing-protocol)
+    """
+
+    def __init__(
+        self,
+        device: str | None,
+    ) -> None:
+        """Initialize serial connection to TKey device.
+
+        Args:
+            device: Optional serial port path (e.g., `/dev/ttyACM0`). If None,
+                the port is auto-detected.
+
+        Raises:
+            TKeyNotFoundError: If no TKey device is found.
+            TKeyError: If the serial connection fails to open.
+        """
+
+        self._conn: SerialConnection | None = None
+        self._fid = 0
+
+        port = self._find_device(device)
+        self._conn = self._get_connection(port, baudrate=62500, timeout=5.0)
+
+    @staticmethod
+    def _find_device(device_path: str | None) -> str:
+        """Discover TKey device serial port using pyserial."""
+
+        ports = list_ports.comports()
+        devices = sorted(
+            p.device for p in ports if p.vid == TKEY_USB_VID and p.pid == TKEY_USB_PID
+        )
+
+        if device_path is None:
+            if not devices:
+                raise TKeyNotFoundError("No TKey devices found")
+            device_path = devices[0]
+        elif device_path not in devices:
+            raise TKeyNotFoundError(f"TKey device {device_path} not found")
+        return device_path
+
+    def _get_connection(
+        self, port: str, baudrate: int, timeout: float
+    ) -> SerialConnection:
+        if sys.platform == "linux":
+            return RawSerialConnection(port, baudrate, timeout)
+        else:
+            try:
+                return serial.Serial(port, baudrate=baudrate, timeout=timeout)
+            except Exception as e:
+                raise TKeyError(f"Failed to open serial port {port}: {e}") from e
+
+    def disconnect(self) -> None:
+        if self._conn is not None:
+            try:
+                self._conn.close()
+            except Exception as e:
+                logger.debug("Failed to close TKey connection: %s", e)
+            self._conn = None
+
+    def __del__(self) -> None:
+        self.disconnect()
+
+    def __enter__(self: _TKey) -> _TKey:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.disconnect()
+
+    def _next_fid(self) -> int:
+        """Returns a frame id (rotating sequence [0-3])"""
+        self._fid = (self._fid + 1) % 4
+        return self._fid
+
+    def send(self, cmd: Cmd, data: bytes = b"", timeout: int = -1) -> bytes:
+        """Frame and send a command, then read the first response frame.
+
+        Caller is expected to call recv_response() if the response is longer than one
+        frame.
+
+        Args:
+            cmd: The command to send.
+            data: Optional payload data for the command.
+            timeout: Optional serial timeout in seconds. If -1, the default
+                connection timeout is used.
+
+        Returns:
+            The first response frame as bytes.
+
+        Raises:
+            TKeyError: If the TKey is not connected.
+            TKeyProtocolError: If the data exceeds the command's maximum length.
+            TKeyIOError: If writing the frame fails.
+        """
+        if self._conn is None:
+            raise TKeyError("TKey is not connected")
+
+        old_timeout = self._conn.timeout
+        if timeout >= 0:
+            self._conn.timeout = timeout
+        try:
+            return self._send(cmd, data)
+        finally:
+            if timeout >= 0:
+                self._conn.timeout = old_timeout
+
+    def _send(self, cmd: Cmd, data: bytes = b"") -> bytes:
+        if self._conn is None:
+            raise TKeyError("TKey is not connected")
+
+        fid = self._next_fid()
+
+        expected_len = PROTO_DATA_LENGTH[cmd.len_idx]
+        if len(data) > expected_len - 1:
+            raise TKeyProtocolError("Data exceeds command data length in header")
+
+        header = (fid << 5) | (cmd.endpoint << 3) | cmd.len_idx
+        frame = bytearray(1 + expected_len)
+        frame[0] = header
+        frame[1] = cmd.id
+        if data:
+            frame[2 : 2 + len(data)] = data
+
+        try:
+            self._conn.write(bytes(frame))
+        except Exception as e:
+            raise TKeyIOError(f"Failed to write frame: {e}") from e
+
+        return self.recv_response(cmd)
+
+    def recv_response(self, cmd: Cmd) -> bytes:
+        """Receive and return a response frame.
+
+        `recv_response()` can only be called if there are unread frames from a previous
+        `send()` call for the given command.
+
+        Args:
+            cmd: The command that this response is for.
+
+        Returns:
+            The response frame as bytes.
+
+        Raises:
+            TKeyError: If the TKey is not connected.
+            TKeyIOError: If reading the response from the serial port fails
+                or returns no data.
+            TKeyProtocolError: If the response status is not OK, the response
+                length is invalid, the frame ID/endpoint mismatch, or the
+                response ID is unexpected.
+        """
+        if self._conn is None:
+            raise TKeyError("TKey is not connected")
+
+        try:
+            resp_header_byte = self._conn.read(1)
+        except Exception as e:
+            raise TKeyIOError(f"Failed to read response header: {e}") from e
+
+        if not resp_header_byte:
+            raise TKeyIOError("No response data")
+
+        header_val = resp_header_byte[0]
+        resp_fid = (header_val >> 5) & 3
+        resp_eid = (header_val >> 3) & 3
+        resp_status = (header_val >> 2) & 1
+        resp_len_idx = header_val & 3
+        resp_len = PROTO_DATA_LENGTH[resp_len_idx]
+
+        if resp_status == 1:
+            try:
+                self._conn.read(resp_len)
+            except Exception as e:
+                logger.debug("Failed to read remaining bytes after NOK status: %s", e)
+            raise TKeyProtocolError("Response status code not OK (1)")
+
+        try:
+            resp_data = self._conn.read(resp_len)
+        except Exception as e:
+            raise TKeyIOError(f"Failed to read response data: {e}") from e
+
+        if len(resp_data) != resp_len:
+            raise TKeyProtocolError("Unexpected response data length")
+
+        # Validate frame ID and endpoint
+        if resp_fid != self._fid or resp_eid != cmd.endpoint:
+            raise TKeyProtocolError(
+                f"Response mismatch: expected Frame ID {self._fid} and Endpoint "
+                f"{cmd.endpoint}, got Frame ID {resp_fid} and Endpoint {resp_eid}"
+            )
+
+        rsp = Rsp(resp_data[0], resp_len_idx)
+        if rsp not in cmd.valid_responses:
+            raise TKeyProtocolError(
+                f"Unexpected protocol response for cmd {cmd.id:#x} on endpoint "
+                f"{cmd.endpoint}: response={rsp.id:#x}, len_index={rsp.len_idx}"
+            )
+
+        response = bytearray(1 + resp_len)
+        response[0] = header_val
+        response[1:] = resp_data
+        return bytes(response)
+
+    def load_app(self, app_binary: bytes, secret: str | None = None) -> bool:
+        """Load an application binary into the TKey device.
+
+        Args:
+            app_binary: The raw bytes of the application binary.
+            secret: Optional User Supplied Secret (passphrase) to configure
+                the app with.
+
+        Returns:
+            True if the application was successfully loaded, False if the
+                device was not in firmware mode (i.e. already running an application).
+
+        Raises:
+            TKeyAppError: If the binary is too large, the device is not ready,
+                or the loaded app's digest does not match the local digest.
+            TKeyError: If the device is running an unknown firmware or if loading
+                data fails.
+        """
+        file_size = len(app_binary)
+        if file_size > APP_MAXSIZE:
+            raise TKeyAppError(
+                f"Application binary is too large ({file_size} > {APP_MAXSIZE})"
+            )
+
+        try:
+            # Query firmware name
+            rx = self.send(FwCmd.NAME_VERSION)
+        except TKeyError:
+            # Not in firmware mode
+            # TODO would be nice to only do this on NOK response, not other errors
+            return False
+
+        # we are in firmware mode. Load the app
+        fw_name0 = rx[2:6].decode("ascii").rstrip()
+        fw_name1 = rx[6:10].decode("ascii").rstrip()
+        if fw_name0 != "tk1" or fw_name1 != "mkdf":
+            raise TKeyError(f"TKey is running an unknown firmware {fw_name0, fw_name1}")
+
+        file_digest = hashlib.blake2s(app_binary, digest_size=32).digest()
+
+        data = bytearray(127)
+        data[0:4] = file_size.to_bytes(4, byteorder="little")
+        if secret is not None:
+            data[4] = 1
+            uss = hashlib.blake2s(secret.encode("utf-8"), digest_size=32)
+            data[5 : 5 + 32] = uss.digest()
+
+        response = self.send(FwCmd.LOAD_APP, bytes(data))
+        if response[2] == 1:
+            raise TKeyAppError("Device not ready (STATUS_BAD)")
+
+        result_digest = self._load_app_data(app_binary)
+        if file_digest != result_digest:
+            raise TKeyAppError(
+                "App digest does not match "
+                f"({file_digest.hex()} != {result_digest.hex()})"
+            )
+
+        if self._conn and self._conn.in_waiting:
+            self._conn.read(self._conn.in_waiting)
+
+        return True
+
+    def _load_app_data(self, file_data: bytes) -> bytes:
+        digest = b""
+        offset = 0
+        while offset < len(file_data):
+            chunk = file_data[offset : offset + 127]
+            response = self.send(FwCmd.LOAD_APP_DATA, chunk)
+            response_id = response[1]
+            status = response[2]
+            if status == 1:
+                raise TKeyError("Bad status when writing app data")
+
+            if response_id == FwRsp.LOAD_APP_DATA_READY.id:
+                digest = response[3:35]
+
+            offset += 127
+
+        return digest

keylet-0.1.0/src/keylet/tkey_sign.py

@@ -0,0 +1,271 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 keylet authors
+
+"""Keylet TKey signer implementation"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.resources
+import logging
+from dataclasses import dataclass
+
+from keylet.tkey import Cmd, LenIdx, Rsp, TKey, TKeyAppError, TKeyError
+
+logger = logging.getLogger(__name__)
+
+MU_SIZE = (64).to_bytes(4, byteorder="little")
+
+
+# Static registry of all signer binaries packaged in keylet.resources.
+# First binary in the list is the default binary.
+# Format: (filename, version, name)
+_EMBEDDED_MLDSA_BINS: list[tuple[str, int, tuple[str, str]]] = [
+    ("pqsigner_v3.bin", 3, ("tk1", "pqsn")),
+]
+
+
+@dataclass
+class SignApp:
+    """Configuration and binary data for the TKey device signer application.
+
+    Attributes:
+        binary: The raw bytes of the device application binary.
+        version: The version number of the device application.
+        name: A tuple representing the expected firmware name and app name
+            on the device (defaults to `("tk1", "pqsn")`).
+        sig_size: The size of the generated signature in bytes (defaults to 2420).
+        key_size: The size of the public key in bytes (defaults to 1312).
+    """
+
+    binary: bytes
+    version: int
+    name: tuple[str, str] = ("tk1", "pqsn")
+    sig_size: int = 2420
+    key_size: int = 1312
+
+    @property
+    def digest(self) -> str:
+        """Return the BLAKE2s-256 hex digest of the application binary."""
+        return hashlib.blake2s(self.binary, digest_size=32).hexdigest()
+
+    @classmethod
+    def load_mldsa(
+        cls, version: int | None = None, digest: str | None = None
+    ) -> SignApp:
+        """Load a ML-DSA signer application from package resources.
+
+        If a digest (or prefix) is provided, it returns the binary matching the
+        digest. If a version is provided, it filters by version. If neither is
+        provided, current default binary is loaded.
+
+        TKey key derivation depends on the application binary, so users who want a
+        specific key must provide the binary digest.
+
+        Args:
+            version: The version of the signer application to load.
+            digest: A BLAKE2s-256 hex digest (or prefix) of the target binary.
+
+        Returns:
+            An instance of SignApp configured with the loaded binary.
+
+        Raises:
+            ValueError: If no binary matches the criteria, or if the search
+                is ambiguous (matches multiple binaries).
+        """
+        resources_dir = importlib.resources.files("keylet.resources")
+        matches = []
+
+        # Scan registered binaries
+        for filename, file_ver, name in _EMBEDDED_MLDSA_BINS:
+            # Filter by version if requested
+            if version is not None and file_ver != version:
+                continue
+
+            binary = resources_dir.joinpath(filename).read_bytes()
+            file_digest = hashlib.blake2s(binary, digest_size=32).hexdigest()
+
+            # Filter by digest if requested
+            if digest is not None and not file_digest.startswith(digest.lower()):
+                continue
+
+            matches.append((binary, file_ver, name, filename))
+
+            if digest is None and version is None:
+                # First binary is the default one
+                break
+
+        if not matches:
+            raise ValueError(
+                f"No device binary found matching: version={version}, digest={digest}"
+            )
+
+        if len(matches) > 1:
+            raise ValueError(
+                f"Multiple device binaries found matching: version={version}, "
+                f"digest={digest}."
+            )
+
+        matched_binary, matched_version, matched_name, _ = matches[0]
+        return cls(matched_binary, matched_version, matched_name)
+
+
+class SignRsp:
+    """Application responses"""
+
+    GET_PUBKEY = Rsp(0x02, LenIdx.I128)
+    SET_SIZE = Rsp(0x04, LenIdx.I4)
+    LOAD_DATA = Rsp(0x06, LenIdx.I4)
+    GET_SIG = Rsp(0x08, LenIdx.I128)
+    GET_NAMEVERSION = Rsp(0x0A, LenIdx.I32)
+    GET_FIRMWARE_HASH = Rsp(0x0C, LenIdx.I128)
+
+
+class SignCmd:
+    """Application commands"""
+
+    GET_PUBKEY = Cmd(0x01, 3, LenIdx.I1, (SignRsp.GET_PUBKEY,))
+    SET_SIZE = Cmd(0x03, 3, LenIdx.I32, (SignRsp.SET_SIZE,))
+    LOAD_DATA = Cmd(0x05, 3, LenIdx.I128, (SignRsp.LOAD_DATA,))
+    GET_SIG = Cmd(0x07, 3, LenIdx.I1, (SignRsp.GET_SIG,))
+    GET_NAMEVERSION = Cmd(0x09, 3, LenIdx.I1, (SignRsp.GET_NAMEVERSION,))
+    GET_FIRMWARE_HASH = Cmd(0x0B, 3, LenIdx.I32, (SignRsp.GET_FIRMWARE_HASH,))
+
+
+class TKeySign(TKey):
+    """Client for communicating with the TKey signer application.
+
+    This class extends the base TKey client to implement public key retrieval and
+    signing as defined in the
+    [tkey-pq-device-signer protocol](https://github.com/tillitis/tkey-pq-device-signer).
+    """
+
+    def __init__(
+        self,
+        app: SignApp,
+        device: str | None = None,
+        secret: str | None = None,
+    ) -> None:
+        """Initialize the TKey signing client.
+
+        If the TKey device is in firmware mode, this will automatically load the
+        application binary. If the device is already running an application, it
+        verifies that the running application matches the expected name and version.
+
+        Args:
+            app: The SignApp configuration containing the binary and metadata.
+            device: Optional serial port path (e.g., `/dev/ttyACM0`). If None,
+                the port is auto-detected.
+            secret: Optional User Supplied Secret (passphrase) used as a seed
+                for key derivation.
+
+        Raises:
+            TKeyNotFoundError: If the TKey device cannot be found.
+            TKeyAppError: If loading the application fails or the device is
+                running a mismatched application.
+            TKeyError: For other connection or initialization failures.
+        """
+        super().__init__(device)
+        self.key_size = app.key_size
+        self.sig_size = app.sig_size
+
+        try:
+            if not self.load_app(app.binary, secret):
+                # TKey is not in firmware mode: Query application name and version
+                rx = self.send(SignCmd.GET_NAMEVERSION)
+                name = (
+                    rx[2:6].decode("ascii").rstrip(),
+                    rx[6:10].decode("ascii").rstrip(),
+                )
+                ver = int.from_bytes(rx[10:14], byteorder="little")
+                if name == app.name and ver == app.version:
+                    return  # Signer application is already loaded
+
+                raise TKeyAppError(
+                    f"TKey is running an unknown application {name, ver}, "
+                    f"expected {app.name, app.version}"
+                )
+        except TKeyError:
+            self.disconnect()
+            raise
+
+    def get_pubkey(self) -> bytes:
+        """Retrieve the public key bytes from the TKey device.
+
+        Returns:
+            The raw public key bytes.
+
+        Raises:
+            TKeyIOError: If reading from the serial port fails.
+            TKeyProtocolError: If there is a framing or protocol mismatch.
+        """
+        pubkey = bytearray(self.key_size)
+
+        # Issue command, read first frame
+        rx = self.send(SignCmd.GET_PUBKEY)
+        offset = 0
+
+        while offset < self.key_size:
+            chunk_size = min(self.key_size - offset, 127)
+            pubkey[offset : offset + chunk_size] = rx[2 : 2 + chunk_size]
+            offset += chunk_size
+            if offset < self.key_size:
+                rx = self.recv_response(SignCmd.GET_PUBKEY)
+
+        return bytes(pubkey)
+
+    def sign(self, message: bytes, pub_key: bytes | None = None) -> bytes:
+        """Sign a message using ML-DSA.
+
+        Computes the FIPS 204 external mu using the message and public key,
+        sends it to the device, and retrieves the signature.
+
+        Note:
+            This method blocks and waits (up to 60 seconds) for the user to touch
+            the physical TKey device when it flashes.
+
+        Args:
+            message: The raw bytes of the message/payload to sign.
+            pub_key: The public key bytes used to compute the external mu.
+                If None, the public key is retrieved from the device.
+
+        Returns:
+            The generated signature as raw bytes.
+
+        Raises:
+            TKeyError: If the device returns a bad status during signing.
+            TKeyIOError: If writing or reading from the serial port fails.
+            TKeyProtocolError: If there is a framing or protocol mismatch.
+        """
+        if pub_key is None:
+            pub_key = self.get_pubkey()
+
+        # Compute FIPS 204 external mu
+        tr = hashlib.shake_256(pub_key).digest(64)
+        mu = hashlib.shake_256(tr + b"\x00\x00" + message).digest(64)
+
+        # Set size: in our case mu is always 64 bytes
+        self.send(SignCmd.SET_SIZE, MU_SIZE)
+
+        # Load data: mu fits in single frame
+        self.send(SignCmd.LOAD_DATA, mu)
+
+        # Trigger signing (blocks waiting for touch) and read first frame
+        rx = self.send(SignCmd.GET_SIG, timeout=60)
+
+        # Read remaining frames
+        signature = bytearray(self.sig_size)
+        offset = 0
+
+        while offset < self.sig_size:
+            if rx[2] != 0:
+                raise TKeyError(f"GetSig chunk NOK status: {rx[2]}")
+
+            chunk_size = min(self.sig_size - offset, 126)
+            signature[offset : offset + chunk_size] = rx[3 : 3 + chunk_size]
+            offset += chunk_size
+
+            if offset < self.sig_size:
+                rx = self.recv_response(SignCmd.GET_SIG)
+
+        return bytes(signature)