Ordering of X509Chain.ChainElements

[tyb-dev]

Describe the issue or suggestion

The current documentation for X509Chain.ChainElements does not specify the ordering of the returned certificates. Consumers of the API need to know whether element 0 is the leaf (end-entity) certificate or the root (trust anchor), and how intermediate certificates are ordered in between.

---

Suggested Improvements

1. Add explicit ordering guarantee
   Include a statement such as:

   “The ChainElements collection is ordered from the end-entity (leaf) certificate at index 0, through any intermediates, to the trust anchor (root certificate) at the final index.”

2. Link to authoritative references

   • On Windows, CERT_CHAIN_CONTEXT guarantees that rgpChain[0] is the end certificate and rgpChain[cChain–1] is the final chain element (root) (see CERT_CHAIN_CONTEXT struct).
   • On Linux, OpenSSL’s X509_STORE_CTX_get0_chain() returns a STACK_OF(X509) ordered from leaf to root.

3. Include a minimal example or unit test snippet
   Demonstrate that:

   using var chain = new X509Chain();
   chain.Build(serverCertificate);
   // chain.ChainElements[0] is the leaf cert
   // chain.ChainElements[^1] is the root cert

---

Rationale

• Clarity & Reliability: Making the ordering contract explicit in the XML docs prevents accidental misuse and reduces reliance on implementation details or platforms.
• Cross-Platform Consistency: Consumers targeting multiple runtimes (Windows, Linux, macOS) will have confidence that the API behaves identically everywhere.
• Ease of Testing: Documenting this behavior enables straightforward unit tests and validation.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-security, @vcsjones