keylet 0.6.0__tar.gz → 1.0.0__tar.gz

{keylet-0.6.0 → keylet-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keylet
-Version: 0.6.0
+Version: 1.0.0
 Summary: Client application for Tillitis TKey hardware ML-DSA/Ed25519 signer
 Keywords: ML-DSA,TKey,Tillitis,PQC,sign,signer
 Author: Jussi Kukkonen
@@ -46,15 +46,15 @@ The package installs a `keylet` command-line tool for signing and verification.
 $ 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
+# Get public key, sign, and verify using the saved public key
+$ keylet pubkey --output pub.key
+$ keylet 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 2cd8741 sign README.md
+$ keylet --digest 2cd8741 sign README.md
 
 ```
 
@@ -67,9 +67,9 @@ from keylet import TKeySign, SignApp
 app = SignApp.load_mldsa()
 digest = app.digest
 
-# Initialize the signer with a passphrase
+# Initialize the signer with a passphrase, sign a payload
 with TKeySign(app=app, secret="hunter2") as signer:
-    # Sign a payload
+    pubkey = signer.get_pubkey()
     signature = signer.sign(b"my payload")
 ```
 
@@ -80,13 +80,14 @@ is always used for a specific key:
 # Load application with a digest stored earlier
 app = SignApp.load_mldsa(digest=digest)
 
-# Initialize the signer with a passphrase
+# Initialize the signer with a passphrase, sign a payload
 with TKeySign(app=app, secret="hunter2") as signer:
-    # Sign a payload
+    if signer.get_pubkey() != pubkey:
+        exit("Unexpected signing key: maybe incorrect password?")
     signature = signer.sign(b"my payload")
 ```
 
-See API Reference in [documentation](https://jku.github.io/keylet/) for more details.
+See API Reference in [documentation](https://jku.github.io/keylet/) for more details.   
 
 ## Development
 
@@ -108,3 +109,9 @@ make test
 # run tests, including on-device tests
 make test-device
 ```
+
+### Releasing
+
+* If a major or minor version bump is needed run `uv version --bump=[major|minor]`
+* run `make release` to create version bump commit, release tag and dev version bump commit
+* Push the commits and tag to trigger release workflow: `git push --tags origin main`

{keylet-0.6.0 → keylet-1.0.0}/README.md

@@ -28,15 +28,15 @@ The package installs a `keylet` command-line tool for signing and verification.
 $ 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
+# Get public key, sign, and verify using the saved public key
+$ keylet pubkey --output pub.key
+$ keylet 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 2cd8741 sign README.md
+$ keylet --digest 2cd8741 sign README.md
 
 ```
 
@@ -49,9 +49,9 @@ from keylet import TKeySign, SignApp
 app = SignApp.load_mldsa()
 digest = app.digest
 
-# Initialize the signer with a passphrase
+# Initialize the signer with a passphrase, sign a payload
 with TKeySign(app=app, secret="hunter2") as signer:
-    # Sign a payload
+    pubkey = signer.get_pubkey()
     signature = signer.sign(b"my payload")
 ```
 
@@ -62,13 +62,14 @@ is always used for a specific key:
 # Load application with a digest stored earlier
 app = SignApp.load_mldsa(digest=digest)
 
-# Initialize the signer with a passphrase
+# Initialize the signer with a passphrase, sign a payload
 with TKeySign(app=app, secret="hunter2") as signer:
-    # Sign a payload
+    if signer.get_pubkey() != pubkey:
+        exit("Unexpected signing key: maybe incorrect password?")
     signature = signer.sign(b"my payload")
 ```
 
-See API Reference in [documentation](https://jku.github.io/keylet/) for more details.
+See API Reference in [documentation](https://jku.github.io/keylet/) for more details.   
 
 ## Development
 
@@ -90,3 +91,9 @@ make test
 # run tests, including on-device tests
 make test-device
 ```
+
+### Releasing
+
+* If a major or minor version bump is needed run `uv version --bump=[major|minor]`
+* run `make release` to create version bump commit, release tag and dev version bump commit
+* Push the commits and tag to trigger release workflow: `git push --tags origin main`

keylet-1.0.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "keylet"
+version = "1.0.0"
+description = "Client application for Tillitis TKey hardware ML-DSA/Ed25519 signer"
+readme = "README.md"
+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.authors]]
+name = "Jussi Kukkonen"
+email = "jkukkonen@google.com"
+
+[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",
+]
+uv = ["uv"]
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "BLE001",
+    "PLR2004",
+    "COM812",
+    "D",
+    "EM",
+    "TRY003",
+    "PYI019",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/keylet/bin/**" = ["T201"]
+"tests/**" = [
+    "S101",
+    "S105",
+    "S106",
+    "SLF001",
+    "ARG002",
+]
+
+[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.6.0/pyproject.toml → keylet-1.0.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "keylet"
-version = "0.6.0"
+version = "1.0.0"
 description = "Client application for Tillitis TKey hardware ML-DSA/Ed25519 signer"
 readme = "README.md"
 authors = [
@@ -39,7 +39,7 @@ dev = [
 uv = ["uv"]
 
 [build-system]
-requires = ["uv_build>=0.11.23,<0.12.0"]
+requires = ["uv_build>=0.12.0,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.ruff.lint]
@@ -61,6 +61,7 @@ ignore = [
 "tests/**" = [
     "S101",   # assert is ok in tests
     "S105",   # hardcoded password is ok in tests
+    "S106",   # hardcoded password is ok in tests
     "SLF001", # Private member access is ok in tests
     "ARG002", # Unused method argument (common with mocks)
 ]

keylet-1.0.0/src/keylet/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 keylet authors
+
+from keylet.tkey import (
+    TKeyAppError,
+    TKeyDeviceBusyError,
+    TKeyError,
+    TKeyIOError,
+    TKeyNOKError,
+    TKeyNotFoundError,
+    TKeyNotInFirmwareModeError,
+    TKeyProtocolError,
+    TKeyUnexpectedAppError,
+)
+from keylet.tkey_sign import SignApp, TKeySign
+
+__all__ = [
+    "SignApp",
+    "TKeyAppError",
+    "TKeyDeviceBusyError",
+    "TKeyError",
+    "TKeyIOError",
+    "TKeyNOKError",
+    "TKeyNotFoundError",
+    "TKeyNotInFirmwareModeError",
+    "TKeyProtocolError",
+    "TKeySign",
+    "TKeyUnexpectedAppError",
+]

keylet-1.0.0/src/keylet/bin/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 keylet authors

{keylet-0.6.0 → keylet-1.0.0}/src/keylet/bin/cli.py

@@ -2,6 +2,7 @@
 # Copyright (c) 2026 keylet authors
 
 import argparse
+import getpass
 import sys
 from collections.abc import Generator
 from contextlib import contextmanager
@@ -11,18 +12,18 @@ 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
+from keylet import SignApp, TKeyNotFoundError, TKeySign, TKeyUnexpectedAppError
 
 
 @contextmanager
 def _app_signer(args: argparse.Namespace) -> Generator[TKeySign, None, None]:
     try:
+        secret = getpass.getpass("Enter passphrase (press Enter for none): ")
         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:
+        with TKeySign(app, secret=secret or None) as signer:
             print(f"Using {args.type} device app with digest {app.digest[:7]}")
             yield signer
     except TKeyNotFoundError as e:
@@ -46,10 +47,19 @@ def cmd_sign(args: argparse.Namespace) -> None:
     if not file_path.exists():
         sys.exit(f"Error: File {args.file} does not exist")
 
-    data = file_path.read_bytes()
+    pubkey = None
+    if args.pubkey is not None:
+        key_path = Path(args.pubkey)
+        if not key_path.exists():
+            sys.exit(f"Error: Public key {args.pubkey} does not exist")
+        pubkey = key_path.read_bytes()
+        # Note that we do not compare the given pubkey to the pubkey from the device
+        # A real application would want to do that to check for passphrase typos etc.
+
     with _app_signer(args) as signer:
         print("Please touch the TKey device when it flashes to sign...")
-        signature = signer.sign(data)
+        with file_path.open("rb") as f:
+            signature = signer.sign(f, pubkey)
 
     sig_path = file_path.with_suffix(file_path.suffix + ".signature")
     sig_path.write_bytes(signature)
@@ -76,8 +86,8 @@ def cmd_verify(args: argparse.Namespace) -> None:
     if args.pubkey:
         pubkey_bytes = Path(args.pubkey).read_bytes()
     else:
+        print("Retrieving public key from device...")
         with _app_signer(args) as signer:
-            print("Retrieving public key from device...")
             pubkey_bytes = signer.get_pubkey()
 
     try:
@@ -101,7 +111,6 @@ def main() -> None:
     parser.add_argument(
         "--digest", help="Optional digest of the device application to use"
     )
-    parser.add_argument("--passphrase")
     parser.add_argument(
         "-t",
         "--type",
@@ -119,6 +128,10 @@ def main() -> None:
     # sign command
     parser_sign = subparsers.add_parser("sign", help="Sign a file")
     parser_sign.add_argument("file", help="File to sign")
+    parser_sign.add_argument(
+        "--pubkey",
+        help="Optional public key file (retrieved from device if not specified)",
+    )
 
     # verify command
     parser_verify = subparsers.add_parser("verify", help="Verify a signature")

{keylet-0.6.0/src/keylet → keylet-1.0.0/src/keylet/resources}/__init__.py

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

{keylet-0.6.0 → keylet-1.0.0}/src/keylet/tkey.py

@@ -138,6 +138,10 @@ class TKeyUnexpectedAppError(TKeyAppError):
     """Raised when TKey is already running a different application."""
 
 
+class TKeyNotInFirmwareModeError(TKeyAppError):
+    """Raised when the TKey is not in firmware mode and firmware mode was required."""
+
+
 class TKey:
     """Base TKey Client
 

{keylet-0.6.0 → keylet-1.0.0}/src/keylet/tkey_sign.py

@@ -8,14 +8,56 @@ from __future__ import annotations
 import hashlib
 import importlib.resources
 import logging
+from collections.abc import Iterable, Iterator
 from dataclasses import dataclass
-
-from keylet.tkey import Cmd, LenIdx, Rsp, TKey, TKeyError, TKeyUnexpectedAppError
+from typing import Protocol, TypeAlias, runtime_checkable
+
+from keylet.tkey import (
+    Cmd,
+    LenIdx,
+    Rsp,
+    TKey,
+    TKeyError,
+    TKeyNotInFirmwareModeError,
+    TKeyUnexpectedAppError,
+)
 
 logger = logging.getLogger(__name__)
 
-MU_SIZE = (64).to_bytes(4, byteorder="little")
 MAX_PAYLOAD_SIZE = 4096
+_STREAM_CHUNK_SIZE = 64 * 1024  # 64 KiB buffer for streaming
+
+
+@runtime_checkable
+class BinaryReader(Protocol):
+    """Protocol for binary streams supporting chunked reads."""
+
+    def read(self, size: int = -1, /) -> bytes: ...
+
+
+SignableMessage: TypeAlias = bytes | BinaryReader | Iterable[bytes]
+
+
+def _iter_chunks(message: SignableMessage) -> Iterator[bytes]:
+    """Yield chunks of bytes from bytes, a binary reader, or an iterable of bytes."""
+    if isinstance(message, bytes):
+        yield message
+    elif isinstance(message, BinaryReader):
+        while chunk := message.read(_STREAM_CHUNK_SIZE):
+            yield chunk
+    else:  # iterable
+        yield from message
+
+
+def _read_bounded(message: SignableMessage, max_size: int) -> bytes:
+    """Read stream into memory up to max_size, failing fast on overflow."""
+    buf = bytearray()
+    for chunk in _iter_chunks(message):
+        buf.extend(chunk)
+        if len(buf) > max_size:
+            raise ValueError(f"Payload size exceeds maximum {max_size} bytes")
+    return bytes(buf)
+
 
 # Static registry of signer binaries (filename, version)
 # First binary in each list is the default binary.
@@ -186,12 +228,15 @@ class TKeySign(TKey):
         app: SignApp,
         device: str | None = None,
         secret: str | None = None,
+        *,
+        require_firmware_mode: bool = False,
     ) -> 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.
+        application binary. If the device is already running an application (and
+        require_firmware_mode is not set), verifies that the running application
+        matches the expected name and version.
 
         Args:
             app: The SignApp configuration containing the binary and metadata.
@@ -199,9 +244,13 @@ class TKeySign(TKey):
                 the port is auto-detected.
             secret: Optional User Supplied Secret (passphrase) used as a seed
                 for key derivation.
+            require_firmware_mode: If True, fail if the device is not in firmware
+                mode instead of attempting to use an already running application.
 
         Raises:
             TKeyNotFoundError: If the TKey device cannot be found.
+            TKeyNotInFirmwareModeError: when require_firmware_mode is set and the
+                device is not in firmware mode.
             TKeyUnexpectedAppError: If loading the application fails or the device is
                 running a mismatched application.
             TKeyError: For other connection or initialization failures.
@@ -213,6 +262,11 @@ class TKeySign(TKey):
 
         try:
             if not self.load_app(app.binary, secret):
+                if require_firmware_mode:
+                    raise TKeyNotInFirmwareModeError(
+                        "TKey is not in firmware mode but require_firmware_mode was set"
+                    )
+
                 # TKey is not in firmware mode: Query application name and version
                 rx = self.send(SignCmd.GET_NAMEVERSION)
                 name = (
@@ -256,22 +310,25 @@ class TKeySign(TKey):
 
         return bytes(pubkey)
 
-    def sign(self, message: bytes, pub_key: bytes | None = None) -> bytes:
+    def sign(self, message: SignableMessage, pub_key: bytes | None = None) -> bytes:
         """Sign a payload.
 
         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.
+        Streaming messages of arbitrary size are supported for ML-DSA.
+        For Ed25519, the message (or stream) must not exceed 4096 bytes.
 
         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. When Ed25519 keys
-                are used, there is a max message size of 4096B. This limitation does
-                not apply to ML-DSA as FIPS 204 external mu is used.
+            message: The raw bytes, binary reader (file-like object), or chunk iterable
+                to sign. For Ed25519, the total message size cannot exceed 4096B.
+                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.
 
@@ -288,13 +345,14 @@ class TKeySign(TKey):
             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)
+            shake = hashlib.shake_256(tr + b"\x00\x00")
+            for chunk in _iter_chunks(message):
+                shake.update(chunk)
+            payload = shake.digest(64)
         else:
-            payload = message
+            payload = _read_bounded(message, MAX_PAYLOAD_SIZE)
 
         # Set size
-        if len(payload) > MAX_PAYLOAD_SIZE:
-            raise ValueError(f"Payload too large {len(payload)} > {MAX_PAYLOAD_SIZE}]")
         self.send(SignCmd.SET_SIZE, len(payload).to_bytes(4, byteorder="little"))
 
         # Load data in chunks

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

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