SPEC-EXTERNAL-SIGNER.md

spec: SPEC-EXTERNAL-SIGNER version: 1 status: draft audience: integrators shipping a signer for a platform mkit does not ship natively (HSM, Secure Enclave, TPM, WebAuthn, KMS)

SPEC-EXTERNAL-SIGNER — mkit external signer protocol v1

The wire contract between the mkit host process and a user-supplied external signer binary. Implementations that follow this spec are drop-in compatible with the external signer selector referenced in SPEC-ATTESTATIONS.md §6.2.

Audience: integrators shipping a signer for a platform mkit does not ship natively — Apple Secure Enclave, Ledger/Trezor, WebAuthn/CTAP, MetaMask/EVM wallet bridges, Makechain, HSMs, etc.

The wire format itself is defined in SPEC-RPC. This document covers the signer-specific aspects: process invocation, conversation flow, capability advertisement, and reference signer behaviors.

1. Scope

mkit asks an external binary to produce a DSSE signature over a specific blob (the PAE) under a specific algorithm, and the binary returns the signature plus a key identifier.

In scope:

• Process invocation, I/O framing, lifetimes, exit-code semantics.
• The signer.proto request/response shapes.
• Capability discovery via Capabilities.
• PIN/authentication round-trips.
• Error surface, size limits, determinism expectations.

Out of scope:

• Key generation or import. The signer is assumed to already possess or have access to the secret. Reference signers that do offer enrollment (mkit-sign-ctap enroll, mkit-sign-tpm keygen) expose it as a separate CLI subcommand outside the protocol.
• The DSSE/in-toto envelope structure (SPEC-ATTESTATIONS).
• Trust-roots configuration (SPEC-ATTESTATIONS §6.5).

2. Process invocation

mkit invokes the configured signer binary as a subprocess. The binary's path is resolved at config time and MUST be absolute; mkit refuses relative paths to close the $PATH resolution race.

$ /absolute/path/to/signer [argv...]

Optional argv tokens come from attest.external_signer_args in the user-scoped config, passed verbatim with no shell interpolation. mkit does NOT pass:

• Any shell metacharacters.
• The PAE on argv (it goes through stdin).
• The algorithm on argv (it goes inside SignRequest).
• Any environment variables it didn't already inherit.

The signer's stdin and stdout are pipes. stderr is also a pipe that mkit drains concurrently for the lifetime of the conversation (it is NOT inherited): a dedicated reader thread discards stderr to EOF, capturing only a bounded diagnostic prefix (1 MiB) for error reporting. This concurrent drain is mandatory — without it a signer that writes a large diagnostic to stderr before emitting its stdout response would deadlock (the signer blocks on a full stderr pipe; mkit blocks reading stdout). Signers MAY write free-form human-readable diagnostics to stderr at any time without fear of blocking.

2.1 Timeout and liveness

mkit bounds the entire signer conversation with a single wall-clock deadline covering every phase: spawn → request-write → response-read → stderr-drain → child-exit. On expiry mkit kills and reaps the child (no zombie, no orphaned hardware session) and returns a typed, phase-named timeout error so the operator can tell a hung touch-prompt (response-read) from a signer that produced a valid response but never exited (child-exit).

The default deadline is 120 seconds, chosen to be generous: hardware-backed signers routinely block on a physical touch, a PIN entry, or a biometric prompt before emitting any output. Operators who drive only fast software signers MAY tighten it via the user-scoped config key attest.external_signer_timeout_secs (an unsigned integer number of seconds; 0 means "deadline already passed" — a hard fail-fast). Like attest.external_signer_path, this key is user-scoped only and is rejected from per-repo .mkit/config: a hostile repo must not be able to set a multi-hour hang or a 0-second denial-of-service.

Signers SHOULD therefore make progress promptly once any required human gesture completes, and MUST NOT assume an unbounded wait.

3. Wire framing

Length-prefixed protobuf-encoded SignerFrame messages on stdin (mkit → signer) and stdout (signer → mkit). The Rust reference signers use the buffa runtime; any protobuf 3/edition 2023 toolchain emitting the same wire bytes is conformant. See SPEC-RPC §1 for the 4-byte LE length prefix, endianness, and the MAX_FRAME_BYTES = 1 MiB cap (frames exceeding the cap are a connection-fatal error).

Schema: rust/crates/mkit-rpc/proto/mkit/rpc/v1/signer/signer.proto.

4. Conversation flow

mkit -> signer:    Hello { protocol = PROTOCOL_VERSION_1,
                            caller_id, want_capabilities }
signer -> mkit:    HelloResponse { protocol, signer_id, capabilities }
mkit -> signer:    SignRequest { algorithm, key_form, key_ref, payload, context }
signer -> mkit:    SignResponse { signature, public_key, algorithm, key_id, ... }
                     OR
                   Error { code, message, details }

The host sends Hello { want_capabilities = true } alone and MUST wait for a HelloResponse selecting protocol v1 with compatible capabilities before sending SignRequest. Missing or unsupported protocol, missing capabilities, and incompatible algorithm/key form are fatal errors. A SignResponse before negotiation is rejected. A terminal Error may abort negotiation at any time; it never authorizes a signing operation.

Both request writes and the handshake response remain under §2.1's single whole-conversation deadline, with concurrent stderr draining. A signing request MUST NOT be sent before successful capability negotiation.

Optional PIN round-trip mid-sign:

signer -> mkit:    PinPrompt { reason, retries_remaining, wants_pin }
mkit   -> signer:  PinResponse { pin }
signer -> mkit:    SignResponse OR Error

mkit MAY send multiple SignRequests on a single connection; the file signer's reference implementation explicitly supports it. The signer MUST process them in order.

5. Capability advertisement

Capabilities in HelloResponse advertises what the signer can do:

mkit MUST verify the requested algorithm + key form against advertised capabilities before sending a SignRequest. Empty algorithm or key-form lists reject every request. The payload MUST fit the advertised cap (0 selects the framing default), and the entire encoded SignerFrame MUST also fit MAX_FRAME_BYTES; protobuf overhead counts toward the frame cap. Oversized requests MUST be rejected before any request bytes are written.

6. SignRequest/SignResponse semantics

Callers MUST treat SignResponse as untrusted. For non-WebAuthn responses, mkit rejects the response unless algorithm echoes the requested algorithm, public_key is present, and signature verifies against public_key and the requested payload. If key_id uses one of the reference canonical prefixes (blake3:, ed25519:, secp256k1:, p256:), mkit recomputes the expected identifier from public_key and rejects mismatches. Unknown key_id prefixes remain opaque and are accepted so third-party signer namespaces keep working. WebAuthn responses are validated by the WebAuthn verifier using the webauthn extension rather than this raw-payload check.

6.1 WebAuthn verifier policy

When a SignResponse carries the webauthn extension, mkit verifies the assertion with a two-layer check:

1. Cryptographic wrapping (always enforced). type == "webauthn.get", clientDataJSON.challenge == base64url-nopad(PAE) (this is the binding that ties the ceremony to the mkit payload), authenticatorData is at least 37 bytes, and the signature verifies against authenticatorData ‖ SHA-256(clientDataJSON) under the returned P-256 public key. The public_key MUST be a valid SEC1 P-256 point. This is what the low-level helper verify_webauthn_wrapping does.

2. Ceremony policy (configurable, layered on top). An independent set of knobs, each defaulting permissive/hardware-friendly:

   Knob	Default	Checks
   expected RP ID	off	authenticatorData[0..32] (rpIdHash) == SHA-256(rp_id)
   allowed origins	off (any)	clientDataJSON.origin is in the allow-list
   require user presence (UP)	off	authenticatorData flag bit 0 set
   require user verification (UV)	off	authenticatorData flag bit 2 set
   allow cross-origin	true	reject clientDataJSON.crossOrigin == true when false
   previous sign counter	off	authenticatorData[33..37] (BE u32) >= previous; rollback rejected

   UP, UV, and the counter are independent knobs on purpose: a strict UV requirement would lock out UP-only roaming authenticators, and a strict counter would reject the many authenticators that always report signCount == 0. The permissive default accepts UP-only and signCount == 0.

All policy inputs derive from the existing authenticator_data and client_data_json fields — there is no proto change. RP-ID hash, flags, and signCount live inside authenticator_data; origin and crossOrigin live inside client_data_json.

Wiring decision. verify_webauthn_wrapping has no verify-attest consumer today — it is invoked only by the external signer's self-consistency check. mkit therefore exposes a policy-aware verify_webauthn_wrapping_with_policy(pae, wrapping, pubkey, sig, &policy) and keeps the bare verify_webauthn_wrapping as a thin, permissive delegate documented as cryptographic-only. The external signer routes its WebAuthn self-consistency check through the policy-aware variant with the signer's configured WebAuthnPolicy (default permissive). This is a ceremony-policy layer only: trust-root binding (which public key is authorized to attest) stays in DSSE envelope verification, not in this helper.

7. Errors

Per-request errors are returned as Error frames; the signer keeps running. Setup-phase failures (no key configured, bad permissions on the key file, missing argv flag) exit non-zero with a stderr message, and the signer MUST NOT emit any frame on stdout in that case — a half-formed response would desync the caller's reader.

Error code semantics: see SPEC-RPC §3.3.

8. Reference signers

Four reference signers ship in contrib/signers/ and exercise the full v1 wire surface: three in Rust (mkit-sign-file, mkit-sign-tpm, mkit-sign-ctap) and one in Swift (mkit-sign-se, using swift-protobuf). All loop on stdin, processing successive Hello / SignRequest pairs until the caller closes the stream; a clean EOF on the length prefix is treated as a graceful shutdown.

8.1 mkit-sign-file

Raw-bytes signer. Reads a 32-byte seed/scalar from disk. Unix permission bits MUST be 0600; otherwise the binary refuses to start.

$ mkit-sign-file --key /home/alice/.mkit/keys/default.key

algorithms = [ED25519, SECP256K1, P256]
key_forms  = [RAW_BYTES]
supports_pin = false
supports_certificate_chain = false
requires_user_presence = false

Reference/development implementation. Not production-grade — the secret is unencrypted on disk.

8.2 mkit-sign-ctap

FIDO2/WebAuthn signer. Drives a plugged-in roaming authenticator (YubiKey, Nitrokey, SoloKey, …) over CTAP-HID.

$ mkit-sign-ctap enroll --rp-id mkit.local --user-name alice
$ mkit-sign-ctap sign  --credential-id <base64url> [--pin <pin>]

algorithms = [P256]
key_forms  = [OPAQUE_HANDLE]            # the credential_id
supports_pin = true
supports_certificate_chain = false
requires_user_presence = true

The reference CTAP signer currently supports P-256 credentials only. SignResponse.public_key is required, and SignResponse.webauthn is populated with authenticator_data + client_data_json so the verifier reconstructs the signed input. A CTAP signer that has a credential ID but no local public-key metadata MUST return an error rather than an empty public_key.

--pin on argv is deprecated. It is readable by any other local user on the host via ps / /proc/<pid>/cmdline — the same exposure class docs/THREAT-MODEL.md §3.2 defends key-file confidentiality against — so it MUST NOT be relied on. Omit it: when the authenticator reports it needs a PIN, the reference signer requests one in-band over the PinPrompt/PinResponse round trip (§4) instead. On the host side, mkit-attest's ExternalSigner answers a PinPrompt via its configured PinProvider, which defaults to an interactive terminal prompt and never sources a PIN from argv or an environment variable. The reference signer prints a deprecation warning when --pin is passed.

For compatibility with mkit's current external-signer host path, the reference CTAP signer accepts KEY_FORM_RAW_BYTES only when key_ref is empty and the credential handle is supplied by argv --credential-id. Explicit credential handles should use KEY_FORM_OPAQUE_HANDLE.

8.3 mkit-sign-tpm

TPM 2.0 P-256 signer. Linux-native via tss-esapi (gated behind the tpm2 Cargo feature).

$ mkit-sign-tpm keygen --handle 0x81010001
$ mkit-sign-tpm sign   --handle 0x81010001

algorithms = [P256]
key_forms  = [OPAQUE_HANDLE]            # 4-byte BE persistent handle
supports_pin = false
supports_certificate_chain = false
requires_user_presence = false

SignRequest.key_ref is the persistent handle as a 4-byte big-endian u32; bare-argv --handle populates a per-process default that the signer uses when key_ref is empty.

9. Determinism

The signer MUST be deterministic for a fixed (payload, key) under ECDSA-SHA-256 (RFC 6979) and Ed25519 (RFC 8032). Test fixtures pin specific signature bytes against fixed scalars; non-deterministic signatures break golden-vector tests.

WebAuthn signatures are NOT deterministic (authenticatorData includes a sign counter). Verifiers reconstruct via authenticator_data || SHA-256(client_data_json); the counter does not leak through to the protocol layer.

10. Security model

The signer process is in mkit's TCB. mkit verifies that the returned signature matches the returned public_key over the requested payload, and rejects key_id mismatches for known canonical prefixes. A compromised signer can still:

• Sign arbitrary blobs of mkit's choosing.
• Lie about which opaque or non-canonical key_id namespace produced the signature, leading the verifier to attribute the signature to a different key if that namespace is trusted out-of-band.
• Fail closed (error frames) but not fail open.

Mitigations the host SHOULD take:

• Require absolute paths for the signer binary (mkit enforces).
• Verify the signer binary's checksum out-of-band.
• Run the signer under a restricted user/sandbox (systemd DynamicUser=, macOS sandbox-exec, …).

11. Versioning

This document and signer.proto are jointly v1. Wire-compatible additions land in v0.1.x patch releases. Breaking changes bump to v2 with a sibling signer2.proto. See SPEC-RPC §2.

12. Invariants

Properties the mkit host upholds regardless of signer behavior, plus the fail-closed rules signers MUST honor. §10 defines what a compromised signer can still do; nothing below claims otherwise.