From 0d14255bf64dd0e31d6c95f1daa05078bd222f40 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 3 Apr 2026 01:59:32 +0000 Subject: [PATCH 1/5] Initial plan From 0235f1062b3d01beab0d90bd1ffb348c4c618db5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 3 Apr 2026 02:03:13 +0000 Subject: [PATCH 2/5] Add breaking change article for SslStream AIA certificate downloads disabled by default Agent-Logs-Url: https://github.com/dotnet/docs/sessions/2cf0c42e-e0f1-48d8-aff7-196f9738cc53 Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/11.md | 6 ++ .../11/sslstream-aia-downloads-disabled.md | 100 ++++++++++++++++++ docs/core/compatibility/toc.yml | 4 + .../extensions/sslstream-best-practices.md | 3 + 4 files changed, 113 insertions(+) create mode 100644 docs/core/compatibility/networking/11/sslstream-aia-downloads-disabled.md 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..a03d0113151c7 --- /dev/null +++ b/docs/core/compatibility/networking/11/sslstream-aia-downloads-disabled.md @@ -0,0 +1,100 @@ +--- +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, `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 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: + +1. **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. + +1. **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.CustomTrustRoot, + CustomTrustStore = { rootCertificate } + }; + + var sslStream = new SslStream(networkStream); + + await sslStream.AuthenticateAsServerAsync(new SslServerAuthenticationOptions + { + ServerCertificateContext = serverCertificateContext, + ClientCertificateRequired = true, + CertificateChainPolicy = chainPolicy + }); + ``` + +1. **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. + + ```csharp + var chainPolicy = new X509ChainPolicy + { + DisableCertificateDownloads = false // allow AIA downloads + }; + + var sslStream = new SslStream(networkStream); + + await sslStream.AuthenticateAsServerAsync(new SslServerAuthenticationOptions + { + ServerCertificateContext = serverCertificateContext, + ClientCertificateRequired = true, + CertificateChainPolicy = chainPolicy + }); + ``` + +## 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..c99097fdf5cc5 100644 --- a/docs/core/extensions/sslstream-best-practices.md +++ b/docs/core/extensions/sslstream-best-practices.md @@ -148,3 +148,6 @@ 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 . + +> [!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). From 1e4e66d871b3dc537368d0b3437b99080efbad8f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 3 Apr 2026 18:31:46 +0000 Subject: [PATCH 3/5] Initial plan From 58d01b46048db9aa74a01724295f2d3c70b6137e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 3 Apr 2026 18:34:18 +0000 Subject: [PATCH 4/5] Update ordered list rules: ordered lists are for procedural steps only Agent-Logs-Url: https://github.com/dotnet/docs/sessions/cf27aee1-b5b4-4127-b243-417527790fb2 Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- .github/copilot-instructions.md | 4 ++-- .github/instructions/Markdown.WritingStyle.instructions.md | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7e2471e335296..174e209381cfa 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -40,8 +40,8 @@ If unsure, use API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/s Use the following rules to encode special characters in API doc IDs: -1. Encode `#` as `%23` in API doc IDs. For example, `System.String.#ctor` becomes `System.String.%23ctor`. -2. **DO NOT** encode `*` or \` (backtick) characters as `%2A` or `%60` respectively. +- Encode `#` as `%23` in API doc IDs. For example, `System.String.#ctor` becomes `System.String.%23ctor`. +- **DO NOT** encode `*` or \` (backtick) characters as `%2A` or `%60` respectively. ## Code Snippets diff --git a/.github/instructions/Markdown.WritingStyle.instructions.md b/.github/instructions/Markdown.WritingStyle.instructions.md index 39e71b578e3ca..68a4c78975619 100644 --- a/.github/instructions/Markdown.WritingStyle.instructions.md +++ b/.github/instructions/Markdown.WritingStyle.instructions.md @@ -39,6 +39,7 @@ ALWAYS: ### Lists and Punctuation - **CRITICAL: Use Oxford comma in ALL lists (item1, item2, and item3) - NO EXCEPTIONS** +- **MANDATORY: Use ordered lists ONLY for sequential procedural steps - NEVER for non-procedural content** - **MANDATORY: Number ordered lists using "1." for every item (NOT 1., 2., 3.) - ALWAYS USE "1."** - **REQUIRED: Use bullets for unordered lists - NEVER use numbers for unordered content** - **ESSENTIAL: Write complete sentences in lists with proper punctuation** From ca7e81fc2406c0fea3f23606fe767e311e5be83e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 3 Apr 2026 11:38:44 -0700 Subject: [PATCH 5/5] revert unwanted changes --- docs/core/compatibility/11.md | 6 -- .../11/sslstream-aia-downloads-disabled.md | 100 ------------------ docs/core/compatibility/toc.yml | 4 - .../extensions/sslstream-best-practices.md | 3 - 4 files changed, 113 deletions(-) delete mode 100644 docs/core/compatibility/networking/11/sslstream-aia-downloads-disabled.md diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 4bd79618a0c78..8654a6a8b2d52 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -49,12 +49,6 @@ 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 deleted file mode 100644 index a03d0113151c7..0000000000000 --- a/docs/core/compatibility/networking/11/sslstream-aia-downloads-disabled.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -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, `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 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: - -1. **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. - -1. **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.CustomTrustRoot, - CustomTrustStore = { rootCertificate } - }; - - var sslStream = new SslStream(networkStream); - - await sslStream.AuthenticateAsServerAsync(new SslServerAuthenticationOptions - { - ServerCertificateContext = serverCertificateContext, - ClientCertificateRequired = true, - CertificateChainPolicy = chainPolicy - }); - ``` - -1. **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. - - ```csharp - var chainPolicy = new X509ChainPolicy - { - DisableCertificateDownloads = false // allow AIA downloads - }; - - var sslStream = new SslStream(networkStream); - - await sslStream.AuthenticateAsServerAsync(new SslServerAuthenticationOptions - { - ServerCertificateContext = serverCertificateContext, - ClientCertificateRequired = true, - CertificateChainPolicy = chainPolicy - }); - ``` - -## Affected APIs - -- -- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index f5f3d2107aac0..8dcf0e709440b 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -34,10 +34,6 @@ 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 c99097fdf5cc5..63f23da8dfd3f 100644 --- a/docs/core/extensions/sslstream-best-practices.md +++ b/docs/core/extensions/sslstream-best-practices.md @@ -148,6 +148,3 @@ 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 . - -> [!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).