keylet 0.1.0__tar.gz → 0.2.0__tar.gz

keylet-0.2.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.3
+Name: keylet
+Version: 0.2.0
+Summary: Client application for Tillitis TKey hardware 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
+Project-URL: Issues, https://github.com/jku/keylet/issues
+Project-URL: Source, https://github.com/jku/keylet
+Project-URL: Documentation, https://jku.github.io/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.
+
+## Installation
+
+```bash
+pip install keylet
+```
+
+## CLI Usage
+
+The package installs a `keylet` command-line tool forsigning 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.

keylet-0.2.0/README.md

@@ -0,0 +1,62 @@
+# 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.
+
+## Installation
+
+```bash
+pip install keylet
+```
+
+## CLI Usage
+
+The package installs a `keylet` command-line tool forsigning 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.

keylet-0.2.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "keylet"
+version = "0.2.0"
+description = "Client application for Tillitis TKey hardware 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"
+
+[project.urls]
+Issues = "https://github.com/jku/keylet/issues"
+Source = "https://github.com/jku/keylet"
+Documentation = "https://jku.github.io/keylet/"
+
+[dependency-groups]
+dev = [
+    "mypy",
+    "pytest",
+    "ruff",
+    "zizmor",
+    "zensical",
+    "mkdocstrings[python]",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.23,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+
+[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
+    "S",    # flake8-bandit (Security)
+    "SIM",  # flake8-simplify
+    "PT",   # flake8-pytest-style
+    "PTH",  # flake8-use-pathlib
+    "TID",  # flake8-tidy-imports
+    "T20",  # flake8-print
+    "ARG",  # flake8-unused-arguments
+    "SIM",  # flake8-simplify
+]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"src/keylet/bin/cli.py" = ["T201"]
+"tests/**" = [
+    "S101",   # Use of assert
+    "S105",   # Possible hardcoded password
+    "PT009",  # Use regular assert instead of unittest assertEqual
+    "PT027",  # Use pytest.raises instead of unittest assertRaises
+    "ARG002", # Unused method argument (common with mocks)
+]
+
+
+
+[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 that require a physical TKey device",
+]

{keylet-0.1.0 → keylet-0.2.0}/src/keylet/bin/cli.py

@@ -6,22 +6,22 @@ import sys
 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
 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:
+        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:
             pubkey = signer.get_pubkey()
+            print(f"Using device app with digest {app.digest[:7]}.")
             if args.output:
                 Path(args.output).write_bytes(pubkey)
                 print(f"Public key written to {args.output}")
@@ -41,7 +41,12 @@ def cmd_sign(args: argparse.Namespace) -> int:
 
     try:
         data = file_path.read_bytes()
-        with get_signer(args.device, args.passphrase) as signer:
+        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 device app with digest {app.digest[:7]}.")
             print("Please touch the TKey device when it flashes to sign...")
             signature = signer.sign(data)
 
@@ -77,13 +82,22 @@ def cmd_verify(args: argparse.Namespace) -> int:
         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:
+            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 device app with digest {app.digest[:7]}.")
+                print("Retrieving public key from device...")
                 pubkey_bytes = signer.get_pubkey()
 
         # Verify signature using cryptography library
-        pubkey = MLDSA44PublicKey.from_public_bytes(pubkey_bytes)
-        pubkey.verify(sig_bytes, file_bytes)
+        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)
         print("Verification successful!")
         return 0
     except InvalidSignature:
@@ -98,10 +112,15 @@ def main() -> None:
     parser = argparse.ArgumentParser(
         description="Tillitis TKey Keylet CLI testing tool"
     )
+    parser.add_argument("--digest", help="The digest of the device application to use")
+    parser.add_argument("--passphrase", help="User Supplied Secret (passphrase)")
     parser.add_argument(
-        "--device", help="Serial port of the TKey device (e.g. /dev/ttyACM0)"
+        "-t",
+        "--type",
+        choices=["ml-dsa", "ed25519"],
+        default="ml-dsa",
+        help="Signer type (default: %(default)s)",
     )
-    parser.add_argument("--passphrase", help="User Supplied Secret (passphrase)")
 
     subparsers = parser.add_subparsers(dest="command", required=True)
 

{keylet-0.1.0 → keylet-0.2.0}/src/keylet/tkey_sign.py

@@ -17,11 +17,15 @@ 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
+# First binary in each list is the default binary.
+# Format: (filename, version)
+_EMBEDDED_MLDSA_BINS: list[tuple[str, int]] = [
+    ("pqsigner_v3.bin", 3),
+]
+
+_EMBEDDED_ED25519_BINS: list[tuple[str, int]] = [
+    ("ed25519signer_v3.bin", 3),
 ]
 
 
@@ -32,17 +36,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 +53,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 +72,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 +89,62 @@ 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.
+
+        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 +172,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__(
@@ -168,6 +206,7 @@ class TKeySign(TKey):
         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):
@@ -215,10 +254,12 @@ 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
@@ -226,8 +267,8 @@ class TKeySign(TKey):
 
         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.
+            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 +278,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",
-]