keylet 0.1.0__tar.gz → 0.2.1.dev0__tar.gz

keylet-0.2.1.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keylet authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keylet-0.2.1.dev0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: keylet
+Version: 0.2.1.dev0
+Summary: Client application for Tillitis TKey hardware ML-DSA/Ed25519 signer
+Keywords: ML-DSA,TKey,Tillitis,PQC,sign,signer
+Author: Jussi Kukkonen
+Author-email: Jussi Kukkonen <jkukkonen@google.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: cryptography>=48.0.0
+Requires-Dist: pyserial>=3.5
+Requires-Python: >=3.10
+Project-URL: Documentation, https://jku.github.io/keylet/
+Project-URL: Homepage, https://github.com/jku/keylet
+Project-URL: Issues, https://github.com/jku/keylet/issues
+Project-URL: Source, https://github.com/jku/keylet
+Description-Content-Type: text/markdown
+
+# keylet -- Client library for Tillitis TKey
+
+[![keylet on GitHub](https://img.shields.io/badge/GitHub-jku%2Fkeylet-blue?logo=github)](https://github.com/jku/keylet) [![keylet on PyPI](https://img.shields.io/pypi/v/keylet.svg)](https://pypi.org/project/keylet/) [![keylet documentation](https://img.shields.io/badge/Documentation-blue)](https://jku.github.io/keylet/)
+
+Keylet is a Python client library and CLI tool for the [Tillitis TKey](https://www.tillitis.se/products/tkey/) security token, and implements a ML-DSA / Ed25519 signer application for TKey.
+
+TKeys unique feature is that it has no long-term memory: signing keys are _always_ generated from a seed at runtime. This seed is built by combining a Unique Device Secret, a Device Application hash and an optional User Supplied Secret. Both the Device Application and User Supplied Secret are provided at runtime by `keylet`. 
+
+The unique design leads to some API peculiarities:
+
+* User Supplied Secret (passphrase) is not directly validated by keylet: a "wrong" passphrase will just lead to using a different signing key. In practice the calling application should look at `TKeySign.get_pubkey()`: if the key is unexpected, then potentially the wrong passphrase was used.
+* In long-term use (where the same signing key is expected to be used over a period of time) the calling application is responsible for always selecting the same Device Application: `keylet` provides a mechanism for this, see examples.
+* The only way to change the device application or passphrase after initialization is to unplug the device and start over.
+* Signer initialization has an optimization where the initialization succeeds if the TKey has already been initialized with matching device application name and version. Unfortunately `keylet` cannot confirm that the exact device binary is the expected one or that the passphrase is still the same one (but again, the calling application can compare `TKeySign.get_pubkey()` to the expected key)
+
+## Installation
+
+```bash
+pip install keylet
+```
+
+## CLI Usage
+
+The package installs a `keylet` command-line tool for signing and verification. This is primarily a test/demo application for the library.
+
+```bash
+# Sign without a passphrase, then verify
+$ keylet sign README.md
+$ keylet verify README.md
+
+# Get public key, sign with a passphrase, and verify using the saved public key
+$ keylet --passphrase hunter2 pubkey --output pub.key
+$ keylet --passphrase hunter2 sign README.md
+$ keylet verify --pubkey pub.key README.md
+
+# When using keylet long-term, remember to specify device app digest (keylet default
+# app version may change, but you will need a specific application to keep using the
+# same key)
+$ keylet --passphrase hunter2 --digest 186bcf6 sign README.md
+
+```
+
+## Library Usage
+
+```python
+from keylet import TKeySign, SignApp
+
+# Load the default embedded ML-DSA signer
+app = SignApp.load_mldsa()
+digest = app.digest
+
+# Initialize the signer with a passphrase
+with TKeySign(app=app, secret="hunter2") as signer:
+    # Sign a payload
+    signature = signer.sign(b"my payload")
+```
+
+In long-term use, the device app digest should be used to ensure the same application
+is always used for a specific key:
+
+```python
+# Load application with a digest stored earlier
+app = SignApp.load_mldsa(digest=digest)
+
+# Initialize the signer with a passphrase
+with TKeySign(app=app, secret="hunter2") as signer:
+    # Sign a payload
+    signature = signer.sign(b"my payload")
+```
+
+See the [API Reference](https://jku.github.io/keylet/api/) for more details.
+
+## Development
+
+[uv](https://docs.astral.sh/uv/) is a required development tool.
+
+```bash
+# Run keylet CLI from source
+uv run keylet sign README.md
+
+# run linters and type checker
+make lint
+
+# Fix formatting and lint issues
+make fix
+
+# run tests
+make test
+
+# run tests, including on-device tests
+make test-device
+```

keylet-0.2.1.dev0/README.md

@@ -0,0 +1,92 @@
+# keylet -- Client library for Tillitis TKey
+
+[![keylet on GitHub](https://img.shields.io/badge/GitHub-jku%2Fkeylet-blue?logo=github)](https://github.com/jku/keylet) [![keylet on PyPI](https://img.shields.io/pypi/v/keylet.svg)](https://pypi.org/project/keylet/) [![keylet documentation](https://img.shields.io/badge/Documentation-blue)](https://jku.github.io/keylet/)
+
+Keylet is a Python client library and CLI tool for the [Tillitis TKey](https://www.tillitis.se/products/tkey/) security token, and implements a ML-DSA / Ed25519 signer application for TKey.
+
+TKeys unique feature is that it has no long-term memory: signing keys are _always_ generated from a seed at runtime. This seed is built by combining a Unique Device Secret, a Device Application hash and an optional User Supplied Secret. Both the Device Application and User Supplied Secret are provided at runtime by `keylet`. 
+
+The unique design leads to some API peculiarities:
+
+* User Supplied Secret (passphrase) is not directly validated by keylet: a "wrong" passphrase will just lead to using a different signing key. In practice the calling application should look at `TKeySign.get_pubkey()`: if the key is unexpected, then potentially the wrong passphrase was used.
+* In long-term use (where the same signing key is expected to be used over a period of time) the calling application is responsible for always selecting the same Device Application: `keylet` provides a mechanism for this, see examples.
+* The only way to change the device application or passphrase after initialization is to unplug the device and start over.
+* Signer initialization has an optimization where the initialization succeeds if the TKey has already been initialized with matching device application name and version. Unfortunately `keylet` cannot confirm that the exact device binary is the expected one or that the passphrase is still the same one (but again, the calling application can compare `TKeySign.get_pubkey()` to the expected key)
+
+## Installation
+
+```bash
+pip install keylet
+```
+
+## CLI Usage
+
+The package installs a `keylet` command-line tool for signing and verification. This is primarily a test/demo application for the library.
+
+```bash
+# Sign without a passphrase, then verify
+$ keylet sign README.md
+$ keylet verify README.md
+
+# Get public key, sign with a passphrase, and verify using the saved public key
+$ keylet --passphrase hunter2 pubkey --output pub.key
+$ keylet --passphrase hunter2 sign README.md
+$ keylet verify --pubkey pub.key README.md
+
+# When using keylet long-term, remember to specify device app digest (keylet default
+# app version may change, but you will need a specific application to keep using the
+# same key)
+$ keylet --passphrase hunter2 --digest 186bcf6 sign README.md
+
+```
+
+## Library Usage
+
+```python
+from keylet import TKeySign, SignApp
+
+# Load the default embedded ML-DSA signer
+app = SignApp.load_mldsa()
+digest = app.digest
+
+# Initialize the signer with a passphrase
+with TKeySign(app=app, secret="hunter2") as signer:
+    # Sign a payload
+    signature = signer.sign(b"my payload")
+```
+
+In long-term use, the device app digest should be used to ensure the same application
+is always used for a specific key:
+
+```python
+# Load application with a digest stored earlier
+app = SignApp.load_mldsa(digest=digest)
+
+# Initialize the signer with a passphrase
+with TKeySign(app=app, secret="hunter2") as signer:
+    # Sign a payload
+    signature = signer.sign(b"my payload")
+```
+
+See the [API Reference](https://jku.github.io/keylet/api/) for more details.
+
+## Development
+
+[uv](https://docs.astral.sh/uv/) is a required development tool.
+
+```bash
+# Run keylet CLI from source
+uv run keylet sign README.md
+
+# run linters and type checker
+make lint
+
+# Fix formatting and lint issues
+make fix
+
+# run tests
+make test
+
+# run tests, including on-device tests
+make test-device
+```

keylet-0.2.1.dev0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "keylet"
+version = "0.2.1-dev"
+description = "Client application for Tillitis TKey hardware ML-DSA/Ed25519 signer"
+readme = "README.md"
+authors = [
+    { name = "Jussi Kukkonen", email = "jkukkonen@google.com" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography>=48.0.0",
+    "pyserial>=3.5",
+]
+keywords = ["ML-DSA", "TKey", "Tillitis", "PQC", "sign", "signer"]
+
+[project.scripts]
+keylet = "keylet.bin.cli:main"
+
+[project.urls]
+Documentation = "https://jku.github.io/keylet/"
+Homepage = "https://github.com/jku/keylet"
+Issues = "https://github.com/jku/keylet/issues"
+Source = "https://github.com/jku/keylet"
+
+[dependency-groups]
+dev = [
+    "mypy",
+    "pytest",
+    "ruff",
+    "zizmor",
+    "zensical",
+    "mkdocstrings[python]",
+    "types-pyserial",
+]
+
+# pin uv in setup-uv action
+uv = ["uv"]
+
+[build-system]
+requires = ["uv_build>=0.11.23,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "BLE001",   # blind exception
+    "PLR2004",  # magic value
+    "COM812",   # trailing comma
+    "D",        # pydocstyle
+    "EM",       # flake8-errmsg
+    "TRY003",   # long message in exception argument
+    "PYI019"    # typing.Self is only available in >= 3.13
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/keylet/bin/**" = [
+    "T201"    # print is ok in CLI tool
+]
+"tests/**" = [
+    "S101",   # assert is ok in tests
+    "S105",   # hardcoded password is ok in tests
+    "ARG002", # Unused method argument (common with mocks)
+]
+
+[tool.mypy]
+python_version = "3.10"
+pretty = true
+strict = true
+strict_equality = true
+disallow_any_unimported = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unreachable = true
+warn_unused_ignores = true
+
+[tool.pytest]
+markers = [
+    "device: tests that require a physical TKey device",
+]

{keylet-0.1.0 → keylet-0.2.1.dev0}/src/keylet/_serial_hack.py

@@ -98,11 +98,11 @@ class RawSerialConnection:
             # 4. Acquire exclusive access
             tiocexcl = 0x540C
             fcntl.ioctl(fd, tiocexcl, 0)
-
-            return fd
         except Exception:
             os.close(fd)
             raise
+        else:
+            return fd
 
     def write(self, data: bytes) -> int:
         if self._fd is None:

keylet-0.2.1.dev0/src/keylet/bin/cli.py

@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 keylet authors
+
+import argparse
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA44PublicKey
+
+from keylet.tkey import TKeyNotFoundError, TKeyUnexpectedAppError
+from keylet.tkey_sign import SignApp, TKeySign
+
+
+@contextmanager
+def _app_signer(args: argparse.Namespace) -> Generator[TKeySign, None, None]:
+    try:
+        if args.type == "ed25519":
+            app = SignApp.load_ed25519(digest=args.digest)
+        else:
+            app = SignApp.load_mldsa(digest=args.digest)
+        with TKeySign(app, secret=args.passphrase) as signer:
+            print(f"Using {args.type} device app with digest {app.digest[:7]}")
+            yield signer
+    except TKeyNotFoundError as e:
+        sys.exit(f"Error: {e}")
+    except TKeyUnexpectedAppError as e:
+        sys.exit(f"Error: {e}")
+
+
+def cmd_pubkey(args: argparse.Namespace) -> None:
+    with _app_signer(args) 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())
+
+
+def cmd_sign(args: argparse.Namespace) -> None:
+    file_path = Path(args.file)
+    if not file_path.exists():
+        sys.exit(f"Error: File {args.file} does not exist")
+
+    data = file_path.read_bytes()
+    with _app_signer(args) 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}")
+
+
+def cmd_verify(args: argparse.Namespace) -> None:
+    file_path = Path(args.file)
+    if not file_path.exists():
+        sys.exit(f"Error: File {args.file} does not exist")
+
+    sig_path = (
+        Path(args.signature)
+        if args.signature
+        else file_path.with_suffix(file_path.suffix + ".signature")
+    )
+    if not sig_path.exists():
+        sys.exit(f"Error: Signature file {sig_path} does not exist")
+
+    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:
+        with _app_signer(args) as signer:
+            print("Retrieving public key from device...")
+            pubkey_bytes = signer.get_pubkey()
+
+    try:
+        # Verify signature using cryptography
+        if args.type == "ed25519":
+            ed_pubkey = Ed25519PublicKey.from_public_bytes(pubkey_bytes)
+            ed_pubkey.verify(sig_bytes, file_bytes)
+        else:
+            ml_pubkey = MLDSA44PublicKey.from_public_bytes(pubkey_bytes)
+            ml_pubkey.verify(sig_bytes, file_bytes)
+    except InvalidSignature:
+        sys.exit("Verification failed: Invalid signature")
+
+    print("Verification successful!")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="keylet -- Signing tool for Tillitis TKey"
+    )
+    parser.add_argument(
+        "--digest", help="Optional digest of the device application to use"
+    )
+    parser.add_argument("--passphrase")
+    parser.add_argument(
+        "-t",
+        "--type",
+        choices=["ml-dsa", "ed25519"],
+        default="ml-dsa",
+        help="key type (default: %(default)s)",
+    )
+
+    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="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 to verify")
+    parser_verify.add_argument(
+        "--signature", help="Signature file (defaults to <FILE>.signature)"
+    )
+    parser_verify.add_argument(
+        "--pubkey",
+        help="Optional public key file (retrieved from device if not specified)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "pubkey":
+        cmd_pubkey(args)
+    elif args.command == "sign":
+        cmd_sign(args)
+    elif args.command == "verify":
+        cmd_verify(args)
+
+
+if __name__ == "__main__":
+    main()

{keylet-0.1.0 → keylet-0.2.1.dev0}/src/keylet/tkey.py

@@ -3,12 +3,12 @@
 
 from __future__ import annotations
 
+import errno
 import hashlib
 import logging
 import sys
 from dataclasses import dataclass
-from types import TracebackType
-from typing import TypeVar
+from typing import TYPE_CHECKING, TypeVar
 
 import serial
 from serial.tools import list_ports
@@ -18,6 +18,9 @@ from keylet._serial_hack import (
     SerialConnection,
 )
 
+if TYPE_CHECKING:
+    from types import TracebackType
+
 logger = logging.getLogger(__name__)
 
 # USB Vendor & Product ID for TKey
@@ -100,7 +103,7 @@ class FwCmd:
     """Command to send a chunk of application binary data."""
 
 
-_TKey = TypeVar("_TKey", bound="TKey")
+Self = TypeVar("Self", bound="TKey")
 
 
 class TKeyError(Exception):
@@ -111,6 +114,10 @@ class TKeyNotFoundError(TKeyError):
     """A TKey device was not found"""
 
 
+class TKeyDeviceBusyError(TKeyError):
+    """Raised when the TKey device is already in use."""
+
+
 class TKeyAppError(TKeyError):
     """Raised when loading the application fails."""
 
@@ -123,6 +130,14 @@ class TKeyProtocolError(TKeyError):
     """Raised upon protocol errors in command or response."""
 
 
+class TKeyNOKError(TKeyProtocolError):
+    """Raised when the TKey device returns a NOK (Not OK) status."""
+
+
+class TKeyUnexpectedAppError(TKeyAppError):
+    """Raised when TKey is already running a different application."""
+
+
 class TKey:
     """Base TKey Client
 
@@ -176,13 +191,19 @@ class TKey:
     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
+        try:
+            if sys.platform == "linux":
+                conn = RawSerialConnection(port, baudrate, timeout)
+            else:
+                conn = serial.Serial(port, baudrate=baudrate, timeout=timeout)
+        except OSError as e:
+            if e.errno in (errno.EBUSY, errno.EACCES) or "Access is denied" in str(e):
+                raise TKeyDeviceBusyError(f"TKey device {port} is busy") from e
+            raise TKeyError(f"Failed to open serial port {port}") from e
+        except Exception as e:
+            raise TKeyError(f"Failed to open serial port {port}") from e
+
+        return conn
 
     def disconnect(self) -> None:
         if self._conn is not None:
@@ -195,7 +216,7 @@ class TKey:
     def __del__(self) -> None:
         self.disconnect()
 
-    def __enter__(self: _TKey) -> _TKey:
+    def __enter__(self: Self) -> Self:
         return self
 
     def __exit__(
@@ -310,7 +331,7 @@ class TKey:
                 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)")
+            raise TKeyNOKError("Response status code not OK (1)")
 
         try:
             resp_data = self._conn.read(resp_len)
@@ -366,9 +387,8 @@ class TKey:
         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
+        except TKeyNOKError:
+            # Device returned NOK: we are running an application already
             return False
 
         # we are in firmware mode. Load the app

{keylet-0.1.0 → keylet-0.2.1.dev0}/src/keylet/tkey_sign.py

@@ -10,18 +10,21 @@ import importlib.resources
 import logging
 from dataclasses import dataclass
 
-from keylet.tkey import Cmd, LenIdx, Rsp, TKey, TKeyAppError, TKeyError
+from keylet.tkey import Cmd, LenIdx, Rsp, TKey, TKeyError, TKeyUnexpectedAppError
 
 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")),
+# Static registry of signer binaries (filename, version)
+# First binary in each list is the default binary.
+_EMBEDDED_MLDSA_BINS: list[tuple[str, int]] = [
+    ("pqsigner_v3.bin", 3),
+]
+
+_EMBEDDED_ED25519_BINS: list[tuple[str, int]] = [
+    ("ed25519signer_v3.bin", 3),
 ]
 
 
@@ -32,17 +35,16 @@ class SignApp:
     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).
+        name: Device application name tuple.
+        sig_size: The size of the generated signature in bytes.
+        key_size: The size of the public key in bytes.
     """
 
     binary: bytes
     version: int
-    name: tuple[str, str] = ("tk1", "pqsn")
-    sig_size: int = 2420
-    key_size: int = 1312
+    name: tuple[str, str]
+    sig_size: int
+    key_size: int
 
     @property
     def digest(self) -> str:
@@ -50,34 +52,14 @@ class SignApp:
         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).
-        """
+    def _find_binary(
+        cls, version: int | None, digest: str | None, bins: list[tuple[str, int]]
+    ) -> tuple[bytes, int]:
         resources_dir = importlib.resources.files("keylet.resources")
         matches = []
 
         # Scan registered binaries
-        for filename, file_ver, name in _EMBEDDED_MLDSA_BINS:
+        for filename, file_ver in bins:
             # Filter by version if requested
             if version is not None and file_ver != version:
                 continue
@@ -89,7 +71,7 @@ class SignApp:
             if digest is not None and not file_digest.startswith(digest.lower()):
                 continue
 
-            matches.append((binary, file_ver, name, filename))
+            matches.append((binary, file_ver))
 
             if digest is None and version is None:
                 # First binary is the default one
@@ -106,8 +88,65 @@ class SignApp:
                 f"digest={digest}."
             )
 
-        matched_binary, matched_version, matched_name, _ = matches[0]
-        return cls(matched_binary, matched_version, matched_name)
+        return matches[0]
+
+    @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).
+        """
+
+        binary, version = cls._find_binary(version, digest, _EMBEDDED_MLDSA_BINS)
+        return cls(binary, version, ("tk1", "pqsn"), 2420, 1312)
+
+    @classmethod
+    def load_ed25519(
+        cls, version: int | None = None, digest: str | None = None
+    ) -> SignApp:
+        """Load a Ed25519 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.
+
+        Warning:
+            When Ed25519 is used, there is a 4096K size limit to signing payloads.
+
+        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).
+        """
+        binary, version = cls._find_binary(version, digest, _EMBEDDED_ED25519_BINS)
+        return cls(binary, version, ("tk1", "sign"), 64, 32)
 
 
 class SignRsp:
@@ -135,9 +174,10 @@ class SignCmd:
 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).
+    This class implements public key retrieval and signing as defined in the
+    [tkey-pq-device-signer protocol](https://github.com/tillitis/tkey-pq-device-signer)
+    but is also compatible with the
+    [tkey-device-signer protocol](https://github.com/tillitis/tkey-device-signer).
     """
 
     def __init__(
@@ -161,13 +201,14 @@ class TKeySign(TKey):
 
         Raises:
             TKeyNotFoundError: If the TKey device cannot be found.
-            TKeyAppError: If loading the application fails or the device is
+            TKeyUnexpectedAppError: 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
+        self.name = app.name
 
         try:
             if not self.load_app(app.binary, secret):
@@ -181,7 +222,7 @@ class TKeySign(TKey):
                 if name == app.name and ver == app.version:
                     return  # Signer application is already loaded
 
-                raise TKeyAppError(
+                raise TKeyUnexpectedAppError(
                     f"TKey is running an unknown application {name, ver}, "
                     f"expected {app.name, app.version}"
                 )
@@ -215,19 +256,23 @@ class TKeySign(TKey):
         return bytes(pubkey)
 
     def sign(self, message: bytes, pub_key: bytes | None = None) -> bytes:
-        """Sign a message using ML-DSA.
+        """Sign a payload.
 
-        Computes the FIPS 204 external mu using the message and public key,
-        sends it to the device, and retrieves the signature.
+        Sends payload to device and retrieves the signature.
+
+        For ML-DSA, the FIPS 204 external mu is computed using the message
+        and public key: the mu is sent to device instead of payload.
 
         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.
+            message: The raw bytes of the message/payload to sign. When Ed25519 keys
+                are used, there is a max message size of 4096K. This limitation does
+                not apply to ML-DSA as FIPS 204 external mu is used.
+            pub_key: The public key bytes (only needed for ML-DSA). If not provided,
+                key is retrieved from device.
 
         Returns:
             The generated signature as raw bytes.
@@ -237,18 +282,30 @@ class TKeySign(TKey):
             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)
+        # pqsn = ML-DSA signer, pqnt = no-touch ML-DSA test signer
+        if self.name in [("tk1", "pqsn"), ("tk1", "pqnt")]:
+            # Compute FIPS 204 external mu
+            if pub_key is None:
+                pub_key = self.get_pubkey()
+            tr = hashlib.shake_256(pub_key).digest(64)
+            payload = hashlib.shake_256(tr + b"\x00\x00" + message).digest(64)
+        else:
+            payload = message
+
+        # Set size
+        if len(payload) > 4096:
+            raise ValueError(f"Payload too large {len(payload)} > 4096]")
+        self.send(SignCmd.SET_SIZE, len(payload).to_bytes(4, byteorder="little"))
+
+        # Load data in chunks
+        chunk_size = 127
+        offset = 0
+        while offset < len(payload):
+            chunk = payload[offset : offset + chunk_size]
+            rx = self.send(SignCmd.LOAD_DATA, chunk)
+            if rx[2] != 0:
+                raise TKeyError(f"LoadData chunk NOK status: {rx[2]}")
+            offset += chunk_size
 
         # Trigger signing (blocks waiting for touch) and read first frame
         rx = self.send(SignCmd.GET_SIG, timeout=60)

keylet-0.1.0/PKG-INFO

@@ -1,15 +0,0 @@
-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

@@ -1,4 +0,0 @@
-## 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

@@ -1,64 +0,0 @@
-[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/bin/cli.py

@@ -1,139 +0,0 @@
-# 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()