docs: Breaking change – SslStream server-side AIA certificate downloads disabled by default (.NET 11)

docs/core/compatibility/11.md

@@ -49,6 +49,12 @@ See [Breaking changes in EF Core 11](/ef/core/what-is-new/ef-core-11.0/breaking-
 |-------|-------------------|
 | [Japanese Calendar minimum supported date corrected](globalization/11/japanese-calendar-min-date.md) | Behavioral change |
 
+## Networking
+
+| Title                                                             | Type of change    |
+|-------------------------------------------------------------------|-------------------|
+| [SslStream server-side AIA certificate downloads disabled by default](networking/11/sslstream-aia-downloads-disabled.md) | Behavioral change |
+
 ## JIT compiler
 
 | Title                                                             | Type of change    |

docs/core/compatibility/networking/11/sslstream-aia-downloads-disabled.md

@@ -0,0 +1,84 @@
+---
+title: "Breaking change: SslStream server-side AIA certificate downloads disabled by default"
+description: "Learn about the breaking change in .NET 11 where SslStream disables AIA certificate downloads during server-side client-certificate validation by default."
+ms.date: 04/03/2026
+ai-usage: ai-assisted
+---
+
+# SslStream server-side AIA certificate downloads disabled by default
+
+Starting in .NET 11, <xref:System.Net.Security.SslStream> doesn't download missing intermediate certificates using the Authority Information Access (AIA) extension by default when validating client certificates as a server.
+
+## Version introduced
+
+.NET 11 Preview 3
+
+## Previous behavior
+
+Previously, when `SslStream` validated client certificates as a server, it attempted to download missing intermediate certificates using the AIA extension if the client didn't provide them during the TLS handshake. This behavior occurred even when no custom <xref:System.Net.Security.SslServerAuthenticationOptions.CertificateChainPolicy> was specified.
+
+For example, the following code would attempt to download intermediate certificates via AIA if the client omitted them:
+
+```csharp
+var sslStream = new SslStream(networkStream);
+
+await sslStream.AuthenticateAsServerAsync(new SslServerAuthenticationOptions
+{
+    ServerCertificate = serverCertificate,
+    ClientCertificateRequired = true,
+    CertificateRevocationCheckMode = X509RevocationMode.Online
+});
+```
+
+## New behavior
+
+Starting in .NET 11, `SslStream` disables AIA certificate downloads when operating as a server that validates client certificates. If the client doesn't provide all required intermediate certificates during the TLS handshake, the server no longer attempts to download them. The handshake fails with a certificate validation error unless the server is configured with the required intermediate certificates.
+
+This change only applies when no custom <xref:System.Net.Security.SslServerAuthenticationOptions.CertificateChainPolicy> is provided. If a custom <xref:System.Security.Cryptography.X509Certificates.X509ChainPolicy> is specified, its <xref:System.Security.Cryptography.X509Certificates.X509ChainPolicy.DisableCertificateDownloads> value is respected.
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+Allowing AIA downloads during the TLS handshake can cause significant performance degradation if the AIA server is slow or unresponsive. Additionally, making outbound HTTP requests to client-provided endpoints introduces potential security risks, since an attacker could influence which external endpoints the server contacts. For more details, see the [pull request](https://github.com/dotnet/runtime/pull/125049) that introduced this change.
+
+## Recommended action
+
+Choose one of the following options:
+
+- **Ensure the client sends all required intermediate certificates**: Configure the client to include all intermediate certificates in the TLS handshake. On the client side, use <xref:System.Net.Security.SslClientAuthenticationOptions.ClientCertificateContext> with an <xref:System.Net.Security.SslStreamCertificateContext> that includes the full chain. For most scenarios, creating `SslStreamCertificateContext` handles intermediate certificate management automatically.
+
+- **Provide intermediate certificates in the server's chain policy**: Use <xref:System.Security.Cryptography.X509Certificates.X509ChainPolicy.ExtraStore> to supply the necessary intermediate certificates to the server:
+
+    ```csharp
+    var chainPolicy = new X509ChainPolicy
+    {
+        // Disable AIA downloads (the default in .NET 11)
+        DisableCertificateDownloads = true,
+
+        // Add any necessary intermediate certificates
+        ExtraStore = { intermediateCertificate },
+
+        // If client certificates are issued by a private root CA, specify custom trust
+        TrustMode = X509ChainTrustMode.CustomTrustRoot,
+        CustomTrustStore = { rootCertificate }
+    };
+
+    var sslStream = new SslStream(networkStream);
+
+    await sslStream.AuthenticateAsServerAsync(new SslServerAuthenticationOptions
+    {
+        ServerCertificateContext = serverCertificateContext,
+        ClientCertificateRequired = true,
+        CertificateChainPolicy = chainPolicy
+    });
+    ```
+
+- **Explicitly allow AIA downloads (not recommended)**: Restore the previous behavior by setting <xref:System.Security.Cryptography.X509Certificates.X509ChainPolicy.DisableCertificateDownloads> to `false`. This approach is not recommended due to the associated performance and security risks.
+
+## Affected APIs
+
+- <xref:System.Net.Security.SslStream.AuthenticateAsServer*?displayProperty=fullName>
+- <xref:System.Net.Security.SslStream.AuthenticateAsServerAsync*?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -34,6 +34,10 @@ items:
             items:
               - name: Minimum hardware requirements updated
                 href: jit/11/minimum-hardware-requirements.md
+          - name: Networking
+            items:
+              - name: SslStream server-side AIA certificate downloads disabled by default
+                href: networking/11/sslstream-aia-downloads-disabled.md
           - name: SDK and MSBuild
             items:
               - name: mono launch target not set for .NET Framework apps

docs/core/extensions/sslstream-best-practices.md

@@ -147,4 +147,7 @@ static bool CustomCertificateValidationCallback(
 
 Server applications need to be careful when requiring and validating client certificates. Certificates may contain the [AIA (Authority Information Access)](http://www.pkiglobe.org/auth_info_access.html) extension which specifies where the issuer certificate can be downloaded. The server may therefore attempt to download the issuer certificate from external server when building the <xref:System.Security.Cryptography.X509Certificates.X509Chain> for the client certificate. Similarly, servers may need to contact external servers to ensure that the client certificate has not been revoked.
 
-The need to contact external servers when building and validating the <xref:System.Security.Cryptography.X509Certificates.X509Chain> may expose the application to denial of service attacks if the external servers are slow to respond. Therefore, server applications should configure the <xref:System.Security.Cryptography.X509Certificates.X509Chain> building behavior using the <xref:System.Net.Security.SslServerAuthenticationOptions.CertificateChainPolicy>.
+The need to contact external servers when building and validating the <xref:System.Security.Cryptography.X509Certificates.X509Chain> might expose the application to denial of service attacks if the external servers are slow to respond. Therefore, server applications should configure the <xref:System.Security.Cryptography.X509Certificates.X509Chain> building behavior using the <xref:System.Net.Security.SslServerAuthenticationOptions.CertificateChainPolicy>.
+
+> [!NOTE]
+> Starting in .NET 11, `SslStream` disables AIA certificate downloads by default when validating client certificates as a server. If no custom <xref:System.Net.Security.SslServerAuthenticationOptions.CertificateChainPolicy> is provided, the server won't attempt to fetch missing intermediate certificates via AIA. For more information, see [SslStream server-side AIA certificate downloads disabled by default](../compatibility/networking/11/sslstream-aia-downloads-disabled.md).