diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 8654a6a8b2d52..4bd79618a0c78 100644 --- a/docs/core/compatibility/11.md +++ b/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 | diff --git a/docs/core/compatibility/networking/11/sslstream-aia-downloads-disabled.md b/docs/core/compatibility/networking/11/sslstream-aia-downloads-disabled.md new file mode 100644 index 0000000000000..e1700432cc3d8 --- /dev/null +++ b/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, 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 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 is provided. If a custom is specified, its 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 with an 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 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.CustomRootTrust, + 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 to `false`. This approach is not recommended due to the associated performance and security risks. + +## Affected APIs + +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 8dcf0e709440b..f5f3d2107aac0 100644 --- a/docs/core/compatibility/toc.yml +++ b/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 diff --git a/docs/core/extensions/sslstream-best-practices.md b/docs/core/extensions/sslstream-best-practices.md index 63f23da8dfd3f..c05b588040c68 100644 --- a/docs/core/extensions/sslstream-best-practices.md +++ b/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 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 may expose the application to denial of service attacks if the external servers are slow to respond. Therefore, server applications should configure the building behavior using the . +The need to contact external servers when building and validating the might expose the application to denial of service attacks if the external servers are slow to respond. Therefore, server applications should configure the building behavior using the . + +> [!NOTE] +> Starting in .NET 11, `SslStream` disables AIA certificate downloads by default when validating client certificates as a server. If no custom 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).