docs: the 'openssl genrsa emits PKCS#1' pitfall is stale — genrsa defaults to PKCS#8 since OpenSSL 3.0

[tahirayan]

Summary

Two operator-facing documents warn that openssl genrsa produces a PKCS#1 key which QAuth's
importPKCS8 will reject. That has not been true since OpenSSL 3.0: genrsa now emits
PKCS#8 by default, and -traditional is required to get the old PKCS#1 output.

An operator on any current OpenSSL follows the warning, cannot reproduce the problem it
describes, and is left unsure whether the rest of the key guidance is trustworthy.

Evidence

$ openssl version
OpenSSL 3.5.6 7 Apr 2026

$ openssl genrsa 2048 | head -1
-----BEGIN PRIVATE KEY-----          # PKCS#8, not PKCS#1

Occurrences:

• docs/oidf-op-certification-runbook.md:44 — "Pitfall: openssl genrsa emits PKCS#1
  (-----BEGIN RSA PRIVATE KEY-----), which importPKCS8 rejects."
• .env.example — the same pitfall, per that runbook's own note at line 94 recording it was
  added there under chore: pursue OpenID Foundation OP conformance certification #286.

What is still true

The underlying QAuth requirement is unchanged and worth keeping: private keys must be
PKCS#8 (libs/core/crypto/src/lib/key-management.ts:47-49 calls importPKCS8 directly, so a
BEGIN RSA PRIVATE KEY PEM is rejected), and openssl genpkey remains the right
recommendation. Only the claim about genrsa's default output is wrong.

Tasks

• Qualify the claim in both places — PKCS#1 is what OpenSSL ≤1.1.x emits, or 3.x with
  -traditional; 3.x defaults to PKCS#8
• Keep openssl genpkey as the recommended command, and keep the
  openssl pkcs8 -topk8 -nocrypt conversion recipe for anyone who does have a PKCS#1 key
• Check whether any other doc repeats it

Acceptance Criteria

• No document claims genrsa emits PKCS#1 without version qualification
• The PKCS#8 requirement itself remains clearly stated
• An operator on OpenSSL 3.x reading the key guidance encounters nothing they cannot reproduce

Additional Notes

Found while a new operate/keys.md page was extracted from the certification runbook's key
section: the new page inherited the claim verbatim, and a review checking it against a live
openssl run caught it. Worth noting that no automated guard could have — it is a claim about
an external tool's behaviour, not about this repository, so nothing in the docs invariants suite
has visibility into it. The new page is being corrected on the documentation branch; this issue
covers the two pre-existing occurrences, which sit outside that branch's scope.

References

• libs/core/crypto/src/lib/key-management.ts:47-49 — the actual PKCS#8 requirement
• OpenSSL 3.0 migration notes — genrsa output-format change