Fall back to the PIV management key when the admin channel truncates a generated key

[mmlado]

Summary

piv perso generate-key and piv quickstart fail with TLV value extends beyond buffer on cards whose applet does not chain responses on the secured path. RSA public-key templates are larger than one 256-byte response (270 bytes for RSA-2048), and such a card returns the first 256 bytes with SW 9000 and drops the rest.

The CLI now detects that response and completes the generation over plain APDUs after authenticating the PIV management key (9B), where the card chains normally. Cards that already return the full template follow exactly the same path as before.

Changes

• Detection. RSA mechanism, SW 9000, exactly 256 bytes, and a leading 7F49 header that declares more than arrived. It cannot fire for ECC or for a card that chains.
• Fallback. Plain SELECT, mutual authentication of 9B (GENERAL AUTHENTICATE, AES), then GENERATE as a plain APDU. The transport's existing 61xx handling reassembles the template.
• factory piv preperso set-mgmt-key, new. Loads the 9B value over the admin channel. Refuses to overwrite a value that is set unless --replace is given, and never creates a missing 9B object.
• factory piv preperso status reports whether 9B exists and holds a value.
• PIV_MGMT_KEY, new environment variable (hex, 16/24/32 bytes). --default-keys also supplies the published test value for 9B. Never read from the command line; registered with the redactor.
• JSON. generate-key gains generate_path and management_key; the quickstart generate-key step carries the same two fields. Additive.
• Errors. Management-key failures exit with code 7 and name the stage. A template that still cannot be parsed is a CLI error naming the response length, not a traceback.
• Docs. Command reference, personalization guide, exit codes, glossary, and ADR 0002 recording the decision.
• scripts/test-local.sh, separate commit: runs the CI jobs locally in Docker.

Testing

Local: ruff, ruff format, mypy, 433 unit tests (86 new), Sphinx with -W, and the package build all pass.

On hardware, contact reader:

Card	Result
Applet that truncates, SCP02	RSA-2048 detected the 256-byte response, fell back, and returned the full key. ECC P-256 stayed on the admin channel. status reported the empty 9B before set-mgmt-key and a value after.
Applet that chains, SCP02, personalized before this change with no 9B value	RSA-2048 on the admin channel. The APDU transcript shows no GENERAL AUTHENTICATE addressed to 9B and no extra SELECT.
Applet that chains, SCP03	RSA-2048 on the admin channel, full template.
9B created without PERMIT_MUTUAL	The fallback stops with exit code 7 and names the missing attribute.

Not covered

• The fallback over SCP03. No SCP03 card running a truncating applet was available. The management-key authentication and the plain GENERATE both run outside the secure channel, so the SCP version does not reach them, but that is not a hardware test.
• RSA-3072 and RSA-4096 through the fallback.

🤖 Generated with Claude Code