The Principia Machina/TPC-PY/tpc fingerprint.py: Difference between revisions

Latest revision as of 04:37, 28 September 2026

"""tpc_fingerprint 0.1.0 (DRAFT, pending the pause of landing round 8):
the FINGERPRINT, the KEY ID and the CALL SIGN of D127.1 as PMP-TPM
0.12.0 VOCABULARY (FINGERPRINT, KEY ID, K_TPX) words them, with TEST-KEY
vectors only: "no agent holds K_FP, so TPC-PY fixes the encoding and
computes no real fingerprint" (D127.1).

Reference implementation, Python standard library only (hashlib, hmac);
imports tpc_beta's canon_float for nothing but the harness's number
form. DATA for landing round 8 of branch tpm_project_closeout; not a
declared TPC-PY version and not TPX code. Every refused argument raises
ValueError with a short fixed message, and a refusal never echoes a key.
Keys are passed as lowercase hex (K_TPX: 64 hex, 32 bytes; a per-agent
salt: 32 hex, 16 bytes); the corpus states one fixed TEST KEY and never
a real secret.

hkdf_expand(prk, info, length) -> hex                    (RFC 5869 2.3)
  HKDF-Expand with HMAC-SHA-256: T(1) = HMAC(PRK, info || 0x01), T(i) =
  HMAC(PRK, T(i-1) || info || i); the first length bytes, length <= 255
  x 32. K_TPX is the PRK: D127.1 "K_FP = HKDF-Expand(K_TPX,
  "TPX-FINGERPRINT-1")", no Extract step (PD-SC-24: K_TPX is 32 bytes
  from the CSPRNG, already a uniform key; alternative: HKDF-Extract with
  an empty salt first). prk: hex, at least 32 bytes; info: a string
  (UTF-8), or bytes (the corpus passes RFC 5869's own test vectors as
  info_hex); length in 1..8160.

key_fp(k) -> hex          K_FP = HKDF-Expand(K_TPX, "TPX-FINGERPRINT-1"),
  32 bytes (D127.1; the per-purpose key). agent_key(k, agent_user_id,
  salt) = HKDF-Expand(K_TPX, enc(["TPX-FINGERPRINT-1", agent_user_id,
  salt])) is the per-agent derivation the speculation's 12.1 names; the
  fingerprint of record is under K_FP (D127.1's formula; PD-SC-25).

fingerprint(k, fields) -> dict                                  (D127.1)
  "FP = HMAC-SHA-256(K_FP, enc(["TPX-FINGERPRINT", "1", sponsor_user_id,
  sponsor_registration, agent_user_id, agent_registration, salt,
  cert_serial, cert_time])), enc the D97.1 netstring encoding ...; 64
  lowercase hex, cited in full on the dossier and the declaration line
  and by its first 16 hex as the CALL SIGN". fields: {sponsor_user_id,
  agent_user_id: MediaWiki user_id (integers >= 1, base-10 in the
  netstring); sponsor_registration, agent_registration, cert_time:
  MediaWiki timestamps, 14 digits YYYYMMDDHHMMSS (user_registration's
  own form; PD-SC-26; alternative: integer seconds); salt: 32 hex, the
  16 salt bytes entering the netstring as raw bytes (PD-SC-27;
  alternative: the 32-hex text); cert_serial: the certificate's ordinal
  on the DECLARATIONS page, an integer >= 1}.
  FP1 The netstring is D97's: each field as its byte length in decimal,
      ":", its bytes; a string as UTF-8, an integer as base-10 ASCII, the
      salt as its 16 bytes.
  FP2 The result: fingerprint (64 hex), call_sign (its first 16 hex),
      key_id (of K_TPX), and the preimage as hex for audit.

key_id(k) -> hex          HMAC-SHA-256(K_TPX, "TPX-KEY-ID") truncated to
  16 hex (D127.1): "names the key a fingerprint was made under".
call_sign(fp) -> str      The first 16 hex of a 64-hex fingerprint.
"""

import hashlib
import hmac
import os
import re
import sys

_here = os.path.dirname(os.path.abspath(__file__))
for _p in (_here,):
    if _p not in sys.path:
        sys.path.insert(0, _p)

VERSION = "0.1.0"
PURPOSE_FP = "TPX-FINGERPRINT-1"
TAG_FP = "TPX-FINGERPRINT"
TAG_KEY_ID = "TPX-KEY-ID"
FORM = "1"
_HEX = re.compile(r"[0-9a-f]+")
_TS = re.compile(r"[0-9]{14}")
_FKEYS = ("sponsor_user_id", "sponsor_registration", "agent_user_id",
          "agent_registration", "salt", "cert_serial", "cert_time")


def _is_int(x, lo, hi):
    return type(x) is int and lo <= x <= hi


def _hex_bytes(s, nbytes_min, nbytes_max):
    if type(s) is not str or len(s) % 2 != 0 or _HEX.fullmatch(s) is None:
        return None
    n = len(s) // 2
    if n < nbytes_min or n > nbytes_max:
        return None
    return bytes.fromhex(s)


def _netstring(items):
    out = bytearray()
    for b in items:
        out += str(len(b)).encode("ascii")
        out += b":"
        out += b
    return bytes(out)


def hkdf_expand(prk, info, length):
    key = _hex_bytes(prk, 32, 1024)
    if key is None:
        raise ValueError("key")
    if type(info) is bytes:
        inf = info
    elif type(info) is str:
        inf = info.encode("utf-8")
    else:
        raise ValueError("info")
    if not _is_int(length, 1, 255 * 32):
        raise ValueError("length")
    return _expand_bytes(key, inf, length).hex()


def _expand_bytes(key, info_bytes, length):
    out = b""
    t = b""
    i = 1
    while len(out) < length:
        t = hmac.new(key, t + info_bytes + bytes([i]), hashlib.sha256).digest()
        out += t
        i += 1
    return out[:length]


def key_fp(k):
    key = _hex_bytes(k, 32, 32)
    if key is None:
        raise ValueError("key")
    return _expand_bytes(key, PURPOSE_FP.encode("utf-8"), 32).hex()


def agent_key(k, agent_user_id, salt):
    key = _hex_bytes(k, 32, 32)
    if key is None:
        raise ValueError("key")
    if not _is_int(agent_user_id, 1, 2 ** 53):
        raise ValueError("fields")
    sb = _hex_bytes(salt, 16, 16)
    if sb is None:
        raise ValueError("fields")
    info = _netstring([PURPOSE_FP.encode("utf-8"), str(agent_user_id).encode("ascii"), sb])
    return _expand_bytes(key, info, 32).hex()


def key_id(k):
    key = _hex_bytes(k, 32, 32)
    if key is None:
        raise ValueError("key")
    return hmac.new(key, TAG_KEY_ID.encode("utf-8"), hashlib.sha256).hexdigest()[:16]


def call_sign(fp):
    if type(fp) is not str or len(fp) != 64 or _HEX.fullmatch(fp) is None:
        raise ValueError("fingerprint")
    return fp[:16]


def _fields(fields):
    if type(fields) is not dict:
        raise ValueError("fields")
    for k in _FKEYS:
        if k not in fields:
            raise ValueError("fields")
    for k in fields:
        if k not in _FKEYS:
            raise ValueError("fields")
    for k in ("sponsor_user_id", "agent_user_id", "cert_serial"):
        if not _is_int(fields[k], 1, 2 ** 53):
            raise ValueError("fields")
    for k in ("sponsor_registration", "agent_registration", "cert_time"):
        v = fields[k]
        if type(v) is not str or _TS.fullmatch(v) is None:
            raise ValueError("fields")
    sb = _hex_bytes(fields["salt"], 16, 16)
    if sb is None:
        raise ValueError("fields")
    return sb


def fingerprint(k, fields):
    key = _hex_bytes(k, 32, 32)
    if key is None:
        raise ValueError("key")
    sb = _fields(fields)
    items = [TAG_FP.encode("utf-8"), FORM.encode("utf-8"),
             str(fields["sponsor_user_id"]).encode("ascii"),
             fields["sponsor_registration"].encode("utf-8"),
             str(fields["agent_user_id"]).encode("ascii"),
             fields["agent_registration"].encode("utf-8"),
             sb,
             str(fields["cert_serial"]).encode("ascii"),
             fields["cert_time"].encode("utf-8")]
    pre = _netstring(items)
    kfp = _expand_bytes(key, PURPOSE_FP.encode("utf-8"), 32)
    fp = hmac.new(kfp, pre, hashlib.sha256).hexdigest()
    return {"fingerprint": fp, "call_sign": fp[:16], "key_id": key_id(k),
            "preimage": pre.hex()}


def render_fingerprint(d):
    return "%s|%s|%s|%s" % (d["fingerprint"], d["call_sign"], d["key_id"], d["preimage"])


# ---------------------------------------------------------------- corpus

FNS = ("hkdf", "key_fp", "agent_key", "key_id", "call_sign", "fingerprint")


def run_case(fn, args):
    """One corpus case: the render, or "ERROR:" and the message."""
    if fn not in FNS:
        raise ValueError("fn")
    try:
        if fn == "hkdf":
            info = args["info"]
            if "info_hex" in args:
                if type(args["info_hex"]) is not str or _HEX.fullmatch(args["info_hex"] or "0") is None \
                        or len(args["info_hex"]) % 2:
                    raise ValueError("info")
                info = bytes.fromhex(args["info_hex"])
            return hkdf_expand(args["prk"], info, args["length"])
        if fn == "key_fp":
            return key_fp(args["k"])
        if fn == "agent_key":
            return agent_key(args["k"], args["agent_user_id"], args["salt"])
        if fn == "key_id":
            return key_id(args["k"])
        if fn == "call_sign":
            return call_sign(args["fp"])
        return render_fingerprint(fingerprint(args["k"], args["fields"]))
    except ValueError as ex:
        return "ERROR:" + str(ex)