Copilot instructions

1---
2applyTo: "src/libraries/System.Net.Security/**"
3---
4 
5# System.Net.Security — Folder-Specific Guidance
6 
7## SslStream Lifecycle
8 
9- SslStream wraps an inner stream — disposal must flush pending data, send TLS close_notify, and dispose the inner stream if owned
10- AuthenticateAsClientAsync/AuthenticateAsServerAsync must not be called more than once; guard against re-authentication on an already-authenticated stream
11- SslStream read/write operations must handle TLS record boundaries — a single TLS record may span multiple inner stream reads
12- Renegotiation (TLS 1.2) and post-handshake auth (TLS 1.3) have different flows — do not conflate them
13 
14## Certificate Validation
15 
16- The default certificate validation callback must enforce chain trust and hostname matching — never bypass validation silently
17- Custom RemoteCertificateValidationCallback must receive the full chain and SslPolicyErrors so callers can make informed decisions
18- Certificate selection (LocalCertificateSelectionCallback) must handle cases where no matching certificate is available
19- Client certificate authentication requires that the private key is accessible — handle CryptographicException gracefully
20 
21## TLS Version and Cipher Handling
22 
23- Default to the highest mutually supported TLS version — do not hardcode a specific version
24- SslProtocols.None means "let the OS decide" and is the preferred default
25- ALPN negotiation results must be checked after handshake — a mismatched protocol should fail early, not produce corrupt data
26- When testing TLS behavior, cover minimum version enforcement and disabled protocol rejection
27 
28## Cross-Platform PAL (SChannel / OpenSSL / Apple Security)
29 
30- SChannel (Windows), OpenSSL (Linux), and Apple Security (macOS) have different API surfaces — changes to the managed layer must be tested on all three
31- OpenSSL context caching (SslContexts) must handle concurrent access and expiration correctly
32- Certificate store access differs per platform — Windows uses the system store, Linux uses file-based stores, macOS uses Keychain
33- Native TLS errors must be mapped to AuthenticationException with platform-specific inner exceptions preserved
34 
35## Credential and Session Caching
36 
37- TLS session resumption state must not leak across security boundaries (different hosts or certificate requirements)
38- CredentialCache and credential lifecycle must be managed carefully — stale credentials cause silent authentication failures
39- Do not cache negotiated security parameters beyond the lifetime of the owning SslStream
40 
41## Performance
42 
43- Avoid allocating during the TLS read/write hot path — pre-allocate TLS record buffers
44- Minimize managed-to-native transitions during bulk data transfer by batching reads/writes at the TLS record level
45- Handshake allocations are acceptable — optimize the steady-state data transfer path
46 
47## Security Defaults
48 
49- Never log private keys, session tickets, or pre-master secrets in any trace or diagnostic output
50- Certificate pinning or validation bypass must require explicit opt-in — secure defaults are non-negotiable
51- Ensure downgrade attacks (forcing weaker TLS versions) are prevented by the default configuration
52