age plugin PQ fixes + 1.2.11 packaging (onto composite-PQC master)

- age_plugin: user ECC slots 101-116 (not 133/134), key-type byte, OKSETPRIV
  0xFF keygen, multi-packet decaps, slot validation + hardware-free tests
- client.py: prefer hidraw backend (trustcrypto#89) [surgical — composite PQC work preserved]
- setup.py: enable long_description (markdown), bump 1.2.10 -> 1.2.11; MANIFEST.in

Author: onlykey

MANIFEST.in

@@ -0,0 +1 @@
+include README.md

onlykey/age_plugin/__init__.py

@@ -1,18 +1,56 @@
 """age-plugin-onlykey: age encryption plugin for OnlyKey hardware tokens.
 
 Supports ML-KEM-768 (FIPS 203) and X-Wing hybrid KEM
-(draft-connolly-cfrg-xwing-kem-09) for post-quantum encryption,
-compatible with age v1.3.0's mlkem768x25519 recipient type.
+(draft-connolly-cfrg-xwing-kem-09) for post-quantum encryption.
+
+The plugin produces native ``mlkem768x25519`` stanzas using OnlyKey-managed
+X-Wing keys. This is narrower and more precise than claiming blanket
+compatibility with every age recipient or identity flow.
 """
 
 __version__ = "0.1.0"
 PLUGIN_NAME = "onlykey"
 
-# OnlyKey HID message types (from onlykey.client.Message)
-OKGETPUBKEY = 236
-OKDECRYPT = 240
-OKGENKEY = 230
+# OnlyKey HID opcodes (values match onlykey.client.Message)
+OKGETPUBKEY = 236   # Message.OKGETPUBKEY
+OKDECRYPT = 240     # Message.OKDECRYPT
+OKSETPRIV = 239     # Message.OKSETPRIV — also generates an on-device key when
+                    # the key body is all 0xFF (firmware okcore.cpp set_private
+                    # -> okcrypto_generate_random_key)
+
+# ECC key slots that can hold the 32-byte post-quantum seed.
+#
+# A ML-KEM/X-Wing key is just a 32-byte seed stored in an ordinary ECC key
+# slot, and the algorithm is chosen by the key-type byte (buffer[6]) below —
+# not by the slot number. The slot is therefore caller-selectable, but only
+# across the USER key slots: firmware exposes 101-116 (16 slots) for user keys.
+# Slots 117-132 are RESERVED (e.g. 128 web-derivation, 129/130 HMAC, 131
+# backup, 132 derivation) and must never be used for PQ keys — writing there
+# would clobber internal device keys. Firmware getpubkey/decaps enforce this
+# with a `< 117` gate (okcrypto.cpp); the host mirrors it here.
+ECC_SLOT_MIN = 101
+ECC_SLOT_MAX = 116            # 16 user ECC key slots: 101-116 (117-132 reserved)
+DEFAULT_XWING_SLOT = 101
+DEFAULT_MLKEM_SLOT = 102
+
+
+def validate_ecc_slot(slot):
+    """Raise ValueError unless slot is a user ECC key slot (101-116).
+
+    117-132 are reserved by firmware and are intentionally rejected.
+    """
+    if not (ECC_SLOT_MIN <= int(slot) <= ECC_SLOT_MAX):
+        raise ValueError(
+            f"PQ key slot must be a user ECC slot {ECC_SLOT_MIN}-{ECC_SLOT_MAX} "
+            f"(117-132 are reserved), got {slot}"
+        )
+    return int(slot)
+
+# Firmware key-type identifiers (okcore.h: KEYTYPE_MLKEM768 / KEYTYPE_XWING).
+# Sent in the low nibble of buffer[6] so the device routes the operation.
+KEYTYPE_MLKEM768 = 5
+KEYTYPE_XWING = 6
 
-# OnlyKey reserved key slots for post-quantum
-SLOT_MLKEM = 133
-SLOT_XWING = 134
+# An all-0xFF key body sent with OKSETPRIV tells the firmware to generate the
+# key on-device (gen_key trigger in okcore.cpp).
+GENERATE_ON_DEVICE = b"\xff" * 8

onlykey/age_plugin/cli.py

@@ -18,8 +18,11 @@
 import sys
 import os
 import base64
+import hashlib
 
-from onlykey.age_plugin import __version__, PLUGIN_NAME, SLOT_XWING
+from onlykey.age_plugin import (
+    __version__, PLUGIN_NAME, DEFAULT_XWING_SLOT, validate_ecc_slot,
+)
 from onlykey.age_plugin.protocol import (
     Stanza, b64encode_no_pad, b64decode_no_pad,
     run_identity_v1, run_recipient_v1,
@@ -111,6 +114,12 @@ def bech32_decode(bech: str):
 RECIPIENT_HRP = "age1onlykey"
 IDENTITY_HRP = "age-plugin-onlykey-"  # uppercase AGE-PLUGIN-ONLYKEY- in file
 
+IDENTITY_VERSION = 1
+IDENTITY_FINGERPRINT_LEN = 8
+XWING_RECIPIENT_LEN = 1216
+XWING_STANZA_ENC_LEN = 1120
+FILE_KEY_LEN = 32
+
 
 def encode_recipient(pubkey: bytes) -> str:
     """Encode X-Wing public key as age recipient string."""
@@ -125,7 +134,12 @@ def decode_recipient(recipient: str) -> bytes:
     return data
 
 
-def encode_identity(slot: int = SLOT_XWING) -> str:
+def recipient_fingerprint(pubkey: bytes) -> bytes:
+    """Return a short fingerprint for identity binding."""
+    return hashlib.sha256(pubkey).digest()[:IDENTITY_FINGERPRINT_LEN]
+
+
+def encode_identity(slot: int = DEFAULT_XWING_SLOT) -> str:
     """Encode an identity string. Contains just the slot number."""
     # Identity data: just the slot byte
     data = bytes([slot])
@@ -135,26 +149,52 @@ def encode_identity(slot: int = SLOT_XWING) -> str:
     )
 
 
-def decode_identity(identity: str) -> int:
-    """Decode identity string, returns slot number."""
+def decode_identity(identity: str) -> dict:
+    """Decode identity string.
+
+    Returns a mapping with ``slot``, ``fingerprint``, and ``legacy`` keys.
+    Legacy one-byte identities are supported so older files continue to work.
+    """
     hrp, data = bech32_decode(identity.lower())
-    if data is None or len(data) < 1:
+    if hrp != IDENTITY_HRP or data is None or len(data) < 1:
         raise ValueError(f"Invalid OnlyKey identity: {identity}")
-    return data[0]
 
+    if len(data) == 1:
+        return {
+            "slot": data[0],
+            "fingerprint": None,
+            "legacy": True,
+        }
+
+    if len(data) != 2 + IDENTITY_FINGERPRINT_LEN:
+        raise ValueError(
+            f"Invalid OnlyKey identity payload length: {len(data)}"
+        )
+
+    version = data[0]
+    if version != IDENTITY_VERSION:
+        raise ValueError(f"Unsupported OnlyKey identity version: {version}")
+
+    return {
+        "slot": data[1],
+        "fingerprint": data[2:],
+        "legacy": False,
+    }
 
-def cmd_generate():
+
+
+def cmd_generate(slot: int = DEFAULT_XWING_SLOT):
     """Generate X-Wing keypair on OnlyKey and print recipient/identity."""
     from onlykey.age_plugin.onlykey_hid import OnlyKeyPQ
 
-    print("Generating X-Wing keypair on OnlyKey...", file=sys.stderr)
+    print(f"Generating X-Wing keypair on OnlyKey (ECC slot {slot})...", file=sys.stderr)
     dev = OnlyKeyPQ()
-    pk = dev.xwing_keygen()
+    pk = dev.xwing_keygen(slot)
 
     recipient = encode_recipient(pk)
-    identity = encode_identity(SLOT_XWING)
+    identity = encode_identity(slot)
 
-    print(f"# X-Wing public key (age v1.3.0 mlkem768x25519 compatible)", file=sys.stderr)
+    print("# X-Wing public key (produces native age mlkem768x25519 stanzas)", file=sys.stderr)
     print(f"# Recipient: {recipient}", file=sys.stderr)
     print(file=sys.stderr)
 
@@ -164,29 +204,73 @@ def cmd_generate():
     print(identity)
 
 
-def cmd_recipient():
-    """Print the current X-Wing public key as an age recipient."""
+def cmd_recipient(slot: int = DEFAULT_XWING_SLOT):
+    """Print the X-Wing public key in the given ECC slot as an age recipient."""
     from onlykey.age_plugin.onlykey_hid import OnlyKeyPQ
 
     dev = OnlyKeyPQ()
-    pk = dev.xwing_getpubkey()
+    pk = dev.xwing_getpubkey(slot)
     print(encode_recipient(pk))
 
 
-def cmd_identity():
+def cmd_identity(slot: int = DEFAULT_XWING_SLOT):
     """Print an identity file for use with age -i."""
-    identity = encode_identity(SLOT_XWING)
-    print(f"# age-plugin-onlykey identity (X-Wing slot {SLOT_XWING})")
+    identity = encode_identity(slot)
+    print(f"# age-plugin-onlykey identity (X-Wing ECC slot {slot})")
     print(identity)
 
 
+def _parse_onlykey_identities(identities):
+    parsed = []
+    for identity in identities:
+        try:
+            parsed.append(decode_identity(identity))
+        except ValueError:
+            continue
+    return parsed
+
+
 def unwrap_callback(identities, stanzas_per_file):
     """Plugin identity-v1 callback: unwrap file keys using OnlyKey."""
     from onlykey.age_plugin.onlykey_hid import OnlyKeyPQ
     from onlykey.age_plugin.xwing import open_file_key
 
     results = []
-    dev = None
+    parsed_identities = _parse_onlykey_identities(identities)
+    if not parsed_identities:
+        print("No valid OnlyKey identity supplied.", file=sys.stderr)
+        return results
+
+    dev = OnlyKeyPQ()
+
+    # The identity carries the ECC slot the key lives in; any of the 32 ECC
+    # slots (101-132) is valid. Query that slot's public key and match it.
+    matching_identity = None
+    matching_slot = None
+    for identity in parsed_identities:
+        try:
+            slot = validate_ecc_slot(identity["slot"])
+        except ValueError:
+            continue
+        try:
+            device_pubkey = dev.xwing_getpubkey(slot)
+        except Exception as exc:
+            print(f"Could not read X-Wing key in slot {slot}: {exc}", file=sys.stderr)
+            continue
+        if len(device_pubkey) != XWING_RECIPIENT_LEN:
+            continue
+        if (identity["fingerprint"] is None
+                or identity["fingerprint"] == recipient_fingerprint(device_pubkey)):
+            matching_identity = identity
+            matching_slot = slot
+            break
+
+    if matching_identity is None:
+        print(
+            "OnlyKey identity does not match the connected device's X-Wing public key.",
+            file=sys.stderr,
+        )
+        return results
 
     for file_idx, stanzas in stanzas_per_file.items():
         for stanza in stanzas:
@@ -195,27 +279,32 @@ def unwrap_callback(identities, stanzas_per_file):
                 continue
 
             if len(stanza.args) != 1:
-                continue
+                raise ValueError(
+                    f"Malformed mlkem768x25519 stanza: expected 1 arg, got {len(stanza.args)}"
+                )
 
             # Parse the ciphertext from the stanza argument
             try:
                 enc = b64decode_no_pad(stanza.args[0])
-            except Exception:
-                continue
+            except Exception as exc:
+                raise ValueError(
+                    "Malformed mlkem768x25519 stanza: invalid base64 ciphertext"
+                ) from exc
 
-            if len(enc) != 1120:
-                continue
+            if len(enc) != XWING_STANZA_ENC_LEN:
+                raise ValueError(
+                    f"Malformed mlkem768x25519 stanza: ciphertext must be {XWING_STANZA_ENC_LEN} bytes, got {len(enc)}"
+                )
 
             # Body must be exactly 32 bytes
-            if len(stanza.body) != 32:
-                continue
+            if len(stanza.body) != FILE_KEY_LEN:
+                raise ValueError(
+                    f"Malformed mlkem768x25519 stanza body: expected {FILE_KEY_LEN} bytes, got {len(stanza.body)}"
+                )
 
-            # Connect to OnlyKey if not already
-            if dev is None:
-                dev = OnlyKeyPQ()
 
-            # Send ciphertext to OnlyKey for decapsulation
-            ss = dev.xwing_decaps(enc)
+            # Send ciphertext to OnlyKey for decapsulation (in the matched slot)
+            ss = dev.xwing_decaps(enc, slot=matching_slot)
 
             # Use shared secret to decrypt the file key via HPKE
             try:
@@ -281,13 +370,26 @@ def main():
                 print(f"Unknown state machine: {state_machine}", file=sys.stderr)
                 sys.exit(1)
 
+    # Optional --slot N / --slot=N selects which ECC slot (101-132) holds the key.
+    slot = DEFAULT_XWING_SLOT
+    for i, arg in enumerate(args):
+        if arg == "--slot" and i + 1 < len(args):
+            slot = args[i + 1]
+        elif arg.startswith("--slot="):
+            slot = arg.split("=", 1)[1]
+    try:
+        slot = validate_ecc_slot(slot)
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
     # Direct invocation modes
     if "--generate" in args or "-g" in args:
-        cmd_generate()
+        cmd_generate(slot)
     elif "--recipient" in args or "-r" in args:
-        cmd_recipient()
+        cmd_recipient(slot)
     elif "--identity" in args or "-i" in args:
-        cmd_identity()
+        cmd_identity(slot)
     elif "--version" in args or "-v" in args:
         print(f"age-plugin-onlykey {__version__}")
     elif "--help" in args or "-h" in args:
@@ -301,6 +403,7 @@ def main():
         print("  --generate    Generate X-Wing keypair on OnlyKey")
         print("  --recipient   Print recipient (public key) for encryption")
         print("  --identity    Print identity file for decryption")
+        print("  --slot N      User ECC slot 101-116 to use (default 101)")
         print("  --help        Show full help")
         print()
         print("Quick start:")