Summary

This PR clarifies the ordering of certificates in theX509Chain.ChainElements collection, which was previously undocumented and caused confusion for developers working with certificate chains across different platforms.

Changes Made

Updated the documentation for theChainElements property inX509Chain.xml to include:

1.Explicit Ordering Guarantee

Added clear statement that the collection is ordered from end-entity (leaf) certificate at index 0 to trust anchor (root certificate) at the final index.

2.Cross-Platform Consistency References

• Windows: ReferencesCERT_CHAIN_CONTEXT structure behavior wherergpChain[0] is the end certificate
• Linux/macOS: References OpenSSL'sX509_STORE_CTX_get0_chain() which returns certificates ordered from leaf to root

3.Practical Code Example

Added demonstration showing how to reliably access certificates by their position in the chain:

usingvarchain=newX509Chain();chain.Build(serverCertificate);// chain.ChainElements[0] is the leaf (end-entity) certificate// chain.ChainElements[^1] is the root (trust anchor) certificateConsole.WriteLine("Certificate chain from leaf to root:");for(inti=0;i<chain.ChainElements.Count;i++){varcert=chain.ChainElements[i].Certificate;varrole=i==0?"Leaf":i==chain.ChainElements.Count-1?"Root":"Intermediate";Console.WriteLine($"[{i}]{role}:{cert.Subject}");}

Impact

This documentation enhancement:

• Eliminates ambiguity around certificate chain ordering
• Enables reliable cross-platform code that depends on certificate position
• Provides confidence for developers implementing certificate validation logic
• Maintains backward compatibility (documentation-only change)

The changes are minimal (22 lines added) and focused solely on clarifying existing behavior without modifying any implementation.

Fixes#11359.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn moreCopilot coding agent tips in the docs.