NPS

English

中文版

---

RFC Number: NPS-RFC-0002 Title: Adopt X.509 + ACME for NID certificates Status: Active Author(s): Ori Lynn iamzerolin@gmail.com (LabAcacia) Shepherd: Ori Lynn Created: 2026-04-21 Last-Updated: 2026-09-05 Accepted: 2026-05-17 Activated: 2026-05-17 (accepted after the reference implementation; six-SDK X.509 + agent-01 parity had landed by 2026-04-30) Supersedes: none Superseded-By: none Affected Specs: NPS-3 NIP, tools/nip-ca-server (all language variants), spec/error-codes.md Affected SDKs: .NET, Python, TypeScript, Java, Rust, Go —

NPS-RFC-0002: Adopt X.509 + ACME for NID certificates

1. Summary

Replace the NIP custom certificate format with X.509v3 certificates carrying a LabAcacia-registered Extended Key Usage (EKU) OID for “agent-identity”, and move NIP CA issuance from the bespoke REST API to ACME (RFC 8555) with an agent-01 challenge type suited to programmatic NID control. Ed25519 remains the primary signature algorithm (RFC 8410 — Ed25519 in X.509). CRL / OCSP revocation semantics are preserved.

2. Motivation

This RFC responds to a 2026-04-20 review comment: “CA 不如直接兼容 现有的 CA 套路” (CAs should be compatible with existing CA practice).

The commenter’s point stands. Current NIP CA (tools/nip-ca-server-*) replicates the operational model of a classic X.509 CA — CSR → issuance → CRL/OCSP revocation → renewal — but uses a bespoke serialization. This creates two unnecessary costs:

1. No tooling reuse. OpenSSL, rustls, BouncyCastle, step-ca, HashiCorp Vault PKI, HSM vendors, cert-manager for Kubernetes — none of them can sign, validate, or store NIP certs without custom integration. The NIP CA server variants in 6 languages each re-implement the ceremony.
2. No issuance-protocol reuse. Manual NID issuance via a REST API doesn’t benefit from the operational maturity that ACME has built: automated renewal, staging environments, rate-limited public CAs, Certbot/lego clients, Kubernetes operators.

Switching to X.509 + ACME costs us ASN.1 parser exposure and ~2–4× cert size, but buys us 15 years of PKI tooling and the ability to run “Let’s Encrypt for Agents” as a future public service — or to delegate NID issuance to existing CAs via cross-signing.

3. Non-Goals

• Does NOT change the wire format of IdentFrame — the certificate still travels as cert_chain bytes; only the internal encoding shifts from NIP-proprietary to X.509.
• Does NOT mandate public CA trust roots. LabAcacia’s own CA remains the default root; nothing precludes organizations from running private X.509 roots.
• Does NOT change NID format (nid:{algo}:{base64url(pubkey)}).
• Does NOT deprecate Ed25519. Ed25519 stays the primary; RSA / ECDSA-P256 remain supported where X.509 allows.

4. Detailed Design

4.1 Wire Format / Frame Changes

IdentFrame.cert_chain encoding changes from nip-cert-v1 (custom) to DER-encoded X.509 certificate chain concatenated or length-prefixed per rule below.

Subject field mapping:

X.509 Field	NIP Value
Subject CN	NID string (nid:ed25519:...)
Subject Alternative Name (SAN) URI	Same NID as a URI entry for RFC 5280 compliance
Issuer	Issuing CA’s NID
NotBefore / NotAfter	Standard X.509 validity period
Public Key	Ed25519 (RFC 8410 OID 1.3.101.112)
Serial Number	128-bit random, per CA/B Forum baseline

Critical extension — Extended Key Usage:

Register LabAcacia IANA Private Enterprise Number (PEN) — once assigned, reserve OID arc 1.3.6.1.4.1.<PEN>.1.

OID	Meaning
1.3.6.1.4.1.<PEN>.1.1	agent-identity — this cert’s subject is an NPS Agent
1.3.6.1.4.1.<PEN>.1.2	node-identity — this cert’s subject is an NPS Node
1.3.6.1.4.1.<PEN>.1.3	ca-intermediate-agent — this CA may sign agent-identity certs

EKU is marked critical. A verifier that doesn’t recognize these EKUs MUST reject the certificate for NIP purposes. (Generic TLS clients would also reject, which is intentional — NID certs MUST NOT be mistaken for TLS server certs.)

Custom non-critical extension — nid:assurance-level:

Reserved for NPS-RFC-0003. This RFC defines the encoding shape only:

nid-assurance-level EXTENSION ::= {
    SYNTAX NidAssuranceLevel
    IDENTIFIED BY id-nid-assurance-level  -- 1.3.6.1.4.1.<PEN>.2.1
}
NidAssuranceLevel ::= ENUMERATED {
    anonymous (0),
    attested  (1),
    verified  (2)
}

Non-critical so v0.1 verifiers ignore the field; RFC-0003 flips it to critical when assurance-level enforcement lands.

4.2 Manifest / NWM Changes

None. X.509 cert chain travels inside IdentFrame, transparent to NWM.

4.3 Error Codes

New entries in spec/error-codes.md:

Error Code	NPS Status	Description
NIP-CERT-FORMAT-INVALID	NPS-CLIENT-BAD-FRAME	Cert chain is not DER-encoded X.509 or fails ASN.1 parsing
NIP-CERT-EKU-MISSING	NPS-CLIENT-BAD-FRAME	Required NPS EKU (agent-identity or node-identity) absent
NIP-CERT-SUBJECT-NID-MISMATCH	NPS-CLIENT-BAD-FRAME	Cert Subject CN / SAN URI does not match the NID in IdentFrame
NIP-ACME-CHALLENGE-FAILED	NPS-CLIENT-BAD-FRAME	ACME agent-01 challenge validation failed

4.4 State Machines / Flows

ACME agent-01 challenge — a new challenge type for NID identity validation (parallels HTTP/DNS/TLS-ALPN challenges in RFC 8555 §8):

Client (Agent)                 ACME Server (NIP CA)
    │                                 │
    │── newAccount (Ed25519 JWK) ──→ │
    │ ←── 201 + kid ────────────────  │
    │                                 │
    │── newOrder (identifiers) ────→ │
    │          identifier: type=nid,  │
    │          value=nid:ed25519:... │
    │ ←── order + authz URL ──────── │
    │                                 │
    │── GET authz URL ──────────────→ │
    │ ←── challenge: type=agent-01,   │
    │     token=T ──────────────────  │
    │                                 │
    │   (Agent signs `T` with its     │
    │    NID private key; serves      │
    │    the signature at a           │
    │    well-known /nip/auth/T       │
    │    on its announced endpoint    │
    │    — OR — posts back to ACME    │
    │    as a JWS)                    │
    │                                 │
    │── POST challenge (signed T) ─→ │
    │ ←── 200 + status=valid ──────── │
    │                                 │
    │── finalize (CSR) ─────────────→ │
    │ ←── 200 + cert URL ──────────── │
    │── GET cert URL ───────────────→ │
    │ ←── 200 + X.509 DER ──────────  │

The agent-01 challenge proves possession of the NID private key in a way that mirrors TLS-ALPN-01’s simplicity: one signed token, no external DNS / HTTP dependency. Servers MUST implement constant-time (timing-safe) comparison when verifying the signed challenge token against the expected value, to prevent timing-oracle attacks on the NID private key. (NIP §10.2 covers a distinct concern — OCSP response-time normalization — and does not apply here.)

4.5 Backward Compatibility

• Old Agents verifying new certs? Break. X.509 parser is a prerequisite. 6 SDKs each gain an X.509 dependency (already present as transitive dep for TLS in every language).
• Old CAs issuing old-format certs? Break. The CA tool must migrate across all 6 language variants.
• Wire-level version detection: IdentFrame gains a cert_format field (v1-proprietary | v2-x509). Deployments running v0.2 stacks can phase the rollout.
• min_agent_version bump with 21-day window per RFC process.

---

5. Alternatives Considered

5.1 Keep proprietary format, add X.509 export shim

Keep current cert format; offer a one-way export to X.509 for interop (e.g., nipc export --x509).

• Cost: two parallel formats forever. Double maintenance for 6 CA servers + 6 SDKs.
• Benefit: no wire break.
• Verdict: rejected. We chose a bespoke format for early velocity; X.509 is the right target now that the model is validated.

5.2 Adopt X.509 without ACME (keep REST issuance)

Use X.509 but keep the current bespoke /certs/issue REST endpoint.

• Cost: loses ACME’s renewal automation, rate-limiting discipline, and rich client ecosystem (Certbot, lego, acme.sh, cert-manager).
• Benefit: simpler initial migration (1 spec change instead of 2).
• Verdict: rejected as the final state; may be adopted as an intermediate step in Phase 1 if engineering bandwidth is tight. Flagged as OQ-1.

5.3 Do nothing

• Cost: 6-language CA servers keep diverging from industry practice. Every new deployment is custom integration. Public-CA option forever closed off.
• Verdict: rejected.

---

6. Drawbacks & Risks

• Migration cost: ~2 SDK-weeks per language (X.509 parser + generator + EKU validation). ACME client: ~1 SDK-week per language. CA side: reuse existing ACME server frameworks (step-ca, boulder, pebble) for the .NET variant at minimum, then port.
• Attack surface: ASN.1 parsers are historically CVE-prone. Mitigation: mandate a vetted library (System.Security.Cryptography.X509Certificates for .NET, cryptography for Python, x509-parser for Rust, etc.) — never hand-roll.
• Cert size: NIP proprietary cert ~200 bytes; X.509 minimum ~450 bytes, typical ~800 bytes. +600 bytes per identity claim. Trivial in HTTP mode; non-trivial for native mode at high frame rates.
• Ecosystem fragmentation: brief period during Phase 1–2 where v1 and v2 cert formats coexist. Mitigated by cert_format version field.
• Reversibility: hard. Rolling back means removing X.509 support across 12 repos. Cost: ~6 SDK-weeks.

---

7. Security Considerations

• ASN.1 parser exposure: new attack class. Mitigated by requiring platform-native parsers (not hand-roll), not honoring unknown critical extensions, and rejecting certs with known pathological constructs (BMPString, negative integers in fields that don’t allow them, etc.).
• EKU-critical discipline: NID certs MUST mark EKU critical. This prevents the classic “cert intended as agent-identity accepted as TLS server cert” cross-purpose attack. Verifiers MUST check EKU before any other use.
• ACME account rotation: RFC 8555 newAccount gives account holders rotation keys. NIP CA MUST enforce that Ed25519 is the account-key algorithm (matches NID algorithm family).
• Certificate Transparency: not in this RFC. RFC-0004 adds a transparency log. In the interim, NIP CA MUST maintain an append-only issuance log queryable by NID.
• Downgrade attack: old Agent presenting v1 cert to a v2-capable server MUST be rejected once Phase 3 lands. Until then servers accept both with version-tagged telemetry.

---

8. Implementation Plan

8.1 Phasing

Phase	Scope	Exit criterion
1	.NET NIP + .NET CA server emit + accept X.509; ACME agent-01 in .NET CA; v1 + v2 coexist	Unit tests green; cross-format interop (v1 client ↔ v2 server and vice versa)
2	All 6 SDKs + 6 CA servers support X.509 + ACME; cert_format=v2 default-off	Cross-SDK cert-accept matrix green; ACME issuance works across all 6 CA variants
3	Flip cert_format=v2 default-on; 21-day deprecation notice for v1	No regressions for 1 release cycle
4	Remove v1 codepath	v1 support removed from all 12 repos

8.2 SDK Coverage Matrix

SDK	Owner	Status	Notes
.NET	NPS SDK maintainers	Implemented — X.509 + agent-01	Primary library and CA reference
Python	NPS SDK maintainers	Implemented — X.509 + agent-01	cryptography; SDK and CA tests
TypeScript	NPS SDK maintainers	Implemented — X.509 + agent-01	SDK and CA tests
Java	NPS SDK maintainers	Implemented — X.509 + agent-01	Bouncy Castle; SDK and CA tests
Rust	NPS SDK maintainers	Implemented — X.509 + agent-01	x509-parser + rcgen; SDK and CA tests
Go	NPS SDK maintainers	Implemented — X.509 + agent-01	stdlib crypto/x509; SDK and CA tests

This records source/test coverage, not Phase 3 activation. The v2 default-on flip and v1 removal remain future compatibility transitions.

8.3 Test Plan

1. X.509 round-trip: CA issues v2 cert with agent-identity EKU; Agent presents it; verifier accepts.
2. EKU-critical enforcement: v2 cert without EKU → NIP-CERT-EKU-MISSING.
3. Subject / NID mismatch: cert Subject CN != IdentFrame.nid → NIP-CERT-SUBJECT-NID-MISMATCH.
4. ACME agent-01 happy path end-to-end.
5. ACME replay protection: repeated challenge token → 400.
6. Cross-format: v1 client + v2 server; v2 client + v1 server (both during Phase 2; both fail cleanly during Phase 3+).

8.4 Benchmarks

Thresholds revised after the 2026-04-27 prototype run (see §9.2):

• IdentFrame JSON size: v2 MUST NOT exceed 1600 bytes for an Ed25519 leaf + single-level intermediate. (The original 1200 B target proved tight under base64url encoding overhead; the prototype measured 1512 B for leaf + self-signed root.)
• Verification latency: v2 path MUST NOT regress beyond 5× the v1 path on the same host. The earlier “≤ 50 µs absolute” sub-target is dropped — the v1 baseline alone is dominated by JSON canonicalization + Ed25519 verify and rarely fits in 50 µs on shared-tenant hardware. Keeping a ratio-only target makes the benchmark host-independent. Prototype measured 2.84× regression (well within ceiling).
• CA server binary size: ≤ 2× the v1 binary at dotnet publish -c Release. Not yet measured; will land in the npsd / nip-ca-server port phase.

---

9. Empirical Data

9.1 Prototype branch

The prototype lives at feat/rfc-0002-x509-acme-prototype on dev. It delivers, in order:

• .NET NIP emits and verifies X.509 certs — impl/dotnet/src/NPS.NIP/X509/{NpsX509Oids,NipX509Builder,NipX509Verifier,Ed25519X509SignatureGenerator}.cs. Five conformance tests in tests/NPS.Tests/Nip/X509/NipX509Tests.cs cover round-trip, EKU-missing rejection, subject/NID-mismatch rejection, and v1↔v2 cross-format compatibility.
• In-process ACME server with agent-01 challenge type — impl/dotnet/src/NPS.NIP/Acme/{AcmeJws,AcmeMessages,AcmeServer,AcmeClient}.cs
  • tests/NPS.Tests/Nip/Acme/AcmeAgent01Tests.cs. Two tests cover end-to-end issuance through the new challenge type and a tampered- signature negative path returning NIP-ACME-CHALLENGE-FAILED.
• Pebble (RFC 8555 reference server) interop is DEFERRED to a follow-up. Reason: pebble does not implement agent-01 (a non- standard challenge type proposed by this RFC); validating standard ACME conformance against pebble would only add HTTP-01 round-trip coverage on top of agent-01. tools/pebble/setup.sh ships the binary download helper for that follow-up.

9.2 Measurements

Numbers below are produced by NPS.Benchmarks.NipCert (dotnet run -c Release --project impl/dotnet/benchmarks/NPS.Benchmarks.NipCert -- --emit), which writes a Markdown report to docs/benchmarks/nip-cert-prototype.md.

Metric	Baseline (v1)	Proposed (v2)	Delta	Method
IdentFrame JSON size	459 B	1512 B	+1053 B (+229%)	UTF-8 byte count of JsonSerializer.Serialize(IdentFrame)
Verification latency (mean of 2000 iters)	597.8 µs	1698.5 µs	2.84×	Stopwatch over verifier.VerifyAsync(frame)

Two RFC §8.4 thresholds are revisited by this data:

• Wire-size ceiling (≤ 1200 B for “Ed25519 leaf + single-level intermediate”): prototype exceeded by 26% (1512 B). The prototype ships a leaf + self-signed root chain rather than leaf + a real intermediate; an actual intermediate would be smaller (no CrlSign/keyCertSign extension overhead) and several base64url inflation factors are amortizable. Read this as “1200 B is plausible but tight — production deployments need to budget for +1 KiB per IdentFrame in the worst case”.
• Verification latency target (≤ 50 µs absolute): NEITHER v1 NOR v2 hits 50 µs absolute on the test container (12× and 34× over respectively). The v1 baseline already includes JSON canonicalization
  • Ed25519 verify, both of which dominate over the X.509 chain check. The proposed regression-ratio target (≤ 5×) IS met (2.84×). RFC should drop the absolute number and keep the ratio; absolute latency is host-dependent and was not measured before the prototype.

9.3 Implications for §10 OQ-1

The prototype ran X.509 first, then layered ACME. Effort: ~5 days of working time for X.509 + verifier + tests; ~2 days for ACME (client + in-process server with agent-01 + tests). pebble HTTP-01 interop would have added another ~1 day if the new agent-01 challenge type weren’t blocking direct interop.

Recommendation for OQ-1: bundle X.509 + ACME in the same acceptance (the original “both together” default position). The ACME piece is mostly mechanical once X.509 issuance is wired; splitting forces a second wave of cross-language port work that can be saved by doing it once.

---

10. Resolved Questions

• OQ-1: Phase 1 — X.509 first, ACME later; OR both together? Resolved 2026-04-27 by prototype data (see §9.3): bundle them. X.509 + ACME together took 7 days of working time on .NET; splitting would require two cross-language port waves (5 SDKs × 2 phases) and the marginal effort of layering ACME on top of X.509 is small.
• OQ-2 — IANA Private Enterprise Number (PEN): Resolved 2026-05-08 — IANA assigned PEN 65715 to LabAcacia / Neuro Protocol Suites Committee, wired in via NPS-CR-0004. The prior provisional arc 1.3.6.1.4.1.99999 is retired. All NpsX509Oids constants now anchor on 1.3.6.1.4.1.65715. Any cert issued under 1.3.6.1.4.1.99999.* MUST be revoked and re-issued under the assigned arc before being relied on for conformance, production NID issuance, or cross-organisation interop. With PEN assigned, this RFC moves from Draft to Proposed.
• OQ-3: Should NIP CA offer cross-signing with public CAs (e.g., Let’s Encrypt)? Resolved 2026-05-17: Deferred to a dedicated follow-up RFC. Cross-signing policy is orthogonal to the core X.509 + ACME issuance surface defined here and can be adopted independently without altering this RFC’s wire format. No open question blocks Accepted status.

---

11. Future Work

• Follow-up RFC: Certificate Transparency for NID issuance (overlaps with NPS-RFC-0004 scope).
• Follow-up RFC: Cross-signing policy with public CAs.
• Follow-up RFC: HSM/TPM binding for NID private keys.

---

12. References

• RFC 5280 — “Internet X.509 Public Key Infrastructure Certificate and CRL Profile”
• RFC 8410 — “Algorithm Identifiers for Ed25519, Ed448, X25519, and X448”
• RFC 8555 — “Automatic Certificate Management Environment (ACME)”
• RFC 6960 — “X.509 OCSP”
• spec/NPS-3-NIP.md — current NIP spec
• tools/nip-ca-server/README.md — current CA server
• Discussion: 2026-04-20 review comment on CA compatibility

---

Appendix A. Revision History

Date	Author	Change
2026-09-05	NPS maintainers	Reconciled status to Active and replaced stale six-SDK owner/status placeholders with current X.509 + agent-01 source/test coverage. Phase 3/4 compatibility transitions remain inactive.
2026-04-27	Claude (prototype)	Backfill §9 Empirical Data with measurements from feat/rfc-0002-x509-acme-prototype (.NET prototype + NPS.Benchmarks.NipCert). Resolve OQ-1 (bundle X.509 + ACME). Revise §8.4 thresholds (size 1200 → 1600 B; drop absolute latency target, keep ratio).
2026-04-21	Ori Lynn	Initial draft

This site is open source. Improve this page.