From afa0936233eb0308aa5136a8ea426ee2c1ab13b2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Jun 2025 18:04:25 +0000 Subject: [PATCH 1/6] Initial plan From d5e7963834c8b17989c486180f326597a3564ec0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Jun 2025 18:10:12 +0000 Subject: [PATCH 2/6] Add breaking change documentation for SSL certificate revocation check mode change Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 1 + ...sl-certificate-revocation-check-default.md | 90 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 + 3 files changed, 95 insertions(+) create mode 100644 docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index a3969d610efc7..2e25362e81761 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -65,6 +65,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|-------------------|--------------------| +| [HttpClient/SslStream default certificate revocation check mode changed to Online](networking/10.0/ssl-certificate-revocation-check-default.md) | Behavioral change | Preview 6 | | [Streaming HTTP responses enabled by default in browser HTTP clients](networking/10.0/default-http-streaming.md) | Behavioral change | Preview 3 | ## SDK and MSBuild diff --git a/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md new file mode 100644 index 0000000000000..9ef57648c20d7 --- /dev/null +++ b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md @@ -0,0 +1,90 @@ +--- +title: "Breaking change - HttpClient/SslStream default certificate revocation check mode changed to Online" +description: "Learn about the breaking change in .NET 10 Preview 6 where the default certificate revocation check mode changed from NoCheck to Online." +ms.date: 06/23/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/46824 +--- + +# HttpClient/SslStream default certificate revocation check mode changed to Online + + and default values have changed from `NoCheck` to `Online`. This change enhances security and makes the behavior consistent with . + +## Version introduced + +.NET 10 Preview 6 + +## Previous behavior + + and default values were `NoCheck`, meaning certificate revocation lists weren't checked by default. + +```csharp +var clientOptions = new SslClientAuthenticationOptions +{ + TargetHost = "example.com" + // CertificateRevocationCheckMode defaults to NoCheck +}; + +var serverOptions = new SslServerAuthenticationOptions +{ + ServerCertificate = serverCertificate + // CertificateRevocationCheckMode defaults to NoCheck +}; +``` + +## New behavior + + and default values are `Online`, meaning certificate revocation lists are checked online by default. + +```csharp +var clientOptions = new SslClientAuthenticationOptions +{ + TargetHost = "example.com" + // CertificateRevocationCheckMode defaults to Online +}; + +var serverOptions = new SslServerAuthenticationOptions +{ + ServerCertificate = serverCertificate + // CertificateRevocationCheckMode defaults to Online +}; +``` + +## Type of breaking change + +This is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change enhances security and ensures consistency between APIs related to X.509 certificate revocation checking. + +## Recommended action + +If certificate revocation checking is not desired, specify `X509RevocationMode.NoCheck` explicitly: + +```csharp +var clientOptions = new SslClientAuthenticationOptions +{ + TargetHost = "example.com", + CertificateRevocationCheckMode = X509RevocationMode.NoCheck +}; + +var serverOptions = new SslServerAuthenticationOptions +{ + ServerCertificate = serverCertificate, + CertificateRevocationCheckMode = X509RevocationMode.NoCheck +}; +``` + +In situations where the code might not be modified, previous behavior can be enabled by setting either: + +- `System.Net.Security.NoRevocationCheckByDefault` AppContext switch to `true` +- `DOTNET_SYSTEM_NET_SECURITY_NOREVOCATIONCHECKBYDEFAULT` environment variable to `true` + +## Affected APIs + +- +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index bd8dd49dadfdc..97f6d4021110d 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -56,6 +56,8 @@ items: href: interop/10.0/search-assembly-directory.md - name: Networking items: + - name: HttpClient/SslStream default certificate revocation check mode changed to Online + href: networking/10.0/ssl-certificate-revocation-check-default.md - name: Streaming HTTP responses enabled by default in browser HTTP clients href: networking/10.0/default-http-streaming.md - name: SDK and MSBuild @@ -1910,6 +1912,8 @@ items: items: - name: .NET 10 items: + - name: HttpClient/SslStream default certificate revocation check mode changed to Online + href: networking/10.0/ssl-certificate-revocation-check-default.md - name: Streaming HTTP responses enabled by default in browser HTTP clients href: networking/10.0/default-http-streaming.md - name: .NET 9 From a1fe5a0de4b660ba34a3a30527b44a76e9566d2b Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 24 Jun 2025 11:53:22 +0200 Subject: [PATCH 3/6] human edits --- ...sl-certificate-revocation-check-default.md | 51 +++++-------------- docs/core/compatibility/toc.yml | 2 - 2 files changed, 12 insertions(+), 41 deletions(-) diff --git a/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md index 9ef57648c20d7..f75304068e260 100644 --- a/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md +++ b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md @@ -1,14 +1,14 @@ --- title: "Breaking change - HttpClient/SslStream default certificate revocation check mode changed to Online" -description: "Learn about the breaking change in .NET 10 Preview 6 where the default certificate revocation check mode changed from NoCheck to Online." +description: "Learn about the breaking change in .NET 10 where the default certificate revocation check mode changed from 'NoCheck' to 'Online'." ms.date: 06/23/2025 ai-usage: ai-assisted ms.custom: https://github.com/dotnet/docs/issues/46824 --- -# HttpClient/SslStream default certificate revocation check mode changed to Online +# HttpClient/SslStream default certificate revocation check mode changed to `Online` - and default values have changed from `NoCheck` to `Online`. This change enhances security and makes the behavior consistent with . +The default values of and have changed from `NoCheck` to `Online`. This change enhances security and makes the behavior consistent with . ## Version introduced @@ -16,43 +16,15 @@ ms.custom: https://github.com/dotnet/docs/issues/46824 ## Previous behavior - and default values were `NoCheck`, meaning certificate revocation lists weren't checked by default. - -```csharp -var clientOptions = new SslClientAuthenticationOptions -{ - TargetHost = "example.com" - // CertificateRevocationCheckMode defaults to NoCheck -}; - -var serverOptions = new SslServerAuthenticationOptions -{ - ServerCertificate = serverCertificate - // CertificateRevocationCheckMode defaults to NoCheck -}; -``` +Previously, the default value of and default values was `NoCheck`, meaning certificate revocation lists weren't checked by default. ## New behavior - and default values are `Online`, meaning certificate revocation lists are checked online by default. - -```csharp -var clientOptions = new SslClientAuthenticationOptions -{ - TargetHost = "example.com" - // CertificateRevocationCheckMode defaults to Online -}; - -var serverOptions = new SslServerAuthenticationOptions -{ - ServerCertificate = serverCertificate - // CertificateRevocationCheckMode defaults to Online -}; -``` +Starting in .NET 10, the default value of and is `Online`, meaning certificate revocation lists are checked online by default. ## Type of breaking change -This is a [behavioral change](../../categories.md#behavioral-change). +This change is a [behavioral change](../../categories.md#behavioral-change). ## Reason for change @@ -60,7 +32,7 @@ This change enhances security and ensures consistency between APIs related to X. ## Recommended action -If certificate revocation checking is not desired, specify `X509RevocationMode.NoCheck` explicitly: +If certificate revocation checking is not desired, specify explicitly: ```csharp var clientOptions = new SslClientAuthenticationOptions @@ -76,10 +48,10 @@ var serverOptions = new SslServerAuthenticationOptions }; ``` -In situations where the code might not be modified, previous behavior can be enabled by setting either: +In situations where you can't modify the code, you can enable the previous behavior with one of the following settings: -- `System.Net.Security.NoRevocationCheckByDefault` AppContext switch to `true` -- `DOTNET_SYSTEM_NET_SECURITY_NOREVOCATIONCHECKBYDEFAULT` environment variable to `true` +- Set `System.Net.Security.NoRevocationCheckByDefault` AppContext switch to `true`. +- Set `DOTNET_SYSTEM_NET_SECURITY_NOREVOCATIONCHECKBYDEFAULT` environment variable to `true`. ## Affected APIs @@ -87,4 +59,5 @@ In situations where the code might not be modified, previous behavior can be ena - - - -- +- (when using either or ) +- (when using either or ) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 97f6d4021110d..5bd32a281f55d 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -1912,8 +1912,6 @@ items: items: - name: .NET 10 items: - - name: HttpClient/SslStream default certificate revocation check mode changed to Online - href: networking/10.0/ssl-certificate-revocation-check-default.md - name: Streaming HTTP responses enabled by default in browser HTTP clients href: networking/10.0/default-http-streaming.md - name: .NET 9 From b91447bb465d212769a9bcd5b3569f20b87ebc0a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Jun 2025 10:27:37 +0000 Subject: [PATCH 4/6] Address review feedback: improve wording and consistency Co-authored-by: rzikm <32671551+rzikm@users.noreply.github.com> --- .../10.0/ssl-certificate-revocation-check-default.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md index f75304068e260..eba800a1d40b5 100644 --- a/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md +++ b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md @@ -16,11 +16,11 @@ The default values of and default values was `NoCheck`, meaning certificate revocation lists weren't checked by default. +Previously, the default values of and were , meaning revocation status of peer certificates wasn't checked by default. ## New behavior -Starting in .NET 10, the default value of and is `Online`, meaning certificate revocation lists are checked online by default. +Starting in .NET 10, the default values of and are , meaning revocation status of peer certificates are checked online by default. ## Type of breaking change @@ -48,7 +48,7 @@ var serverOptions = new SslServerAuthenticationOptions }; ``` -In situations where you can't modify the code, you can enable the previous behavior with one of the following settings: +In situations where you can't modify the code, you can restore the previous behavior with one of the following settings: - Set `System.Net.Security.NoRevocationCheckByDefault` AppContext switch to `true`. - Set `DOTNET_SYSTEM_NET_SECURITY_NOREVOCATIONCHECKBYDEFAULT` environment variable to `true`. From 02079a1e2e21994dc6266767bfadff4a50e1aa5d Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 26 Jun 2025 17:25:44 +0200 Subject: [PATCH 5/6] Update docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md Co-authored-by: Radek Zikmund <32671551+rzikm@users.noreply.github.com> --- .../networking/10.0/ssl-certificate-revocation-check-default.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md index eba800a1d40b5..37c82c6369a15 100644 --- a/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md +++ b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md @@ -48,6 +48,8 @@ var serverOptions = new SslServerAuthenticationOptions }; ``` +> [!NOTE] +> Due to a bug on the OSX platform, you might encounter certificate validation failures with in scenarios where the certificate doesn't support revocation checking via OCSP. This is a bug in the underlying platform crypto implementation. To avoid failing the certificate validation if revocation status can't be retrieved, either disable certificate revocation checking as per the previous instructions, or set with set to `X509VerificationFlags.IgnoreEndRevocationUnknown | X509VerificationFlags.IgnoreCertificateAuthorityRevocationUnknown`. In situations where you can't modify the code, you can restore the previous behavior with one of the following settings: - Set `System.Net.Security.NoRevocationCheckByDefault` AppContext switch to `true`. From 251c51531110d7df22e8f1735c70b8e49184c939 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 26 Jun 2025 17:32:49 +0200 Subject: [PATCH 6/6] Add line break --- .../networking/10.0/ssl-certificate-revocation-check-default.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md index 37c82c6369a15..a012c0e6dc9e9 100644 --- a/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md +++ b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md @@ -50,6 +50,7 @@ var serverOptions = new SslServerAuthenticationOptions > [!NOTE] > Due to a bug on the OSX platform, you might encounter certificate validation failures with in scenarios where the certificate doesn't support revocation checking via OCSP. This is a bug in the underlying platform crypto implementation. To avoid failing the certificate validation if revocation status can't be retrieved, either disable certificate revocation checking as per the previous instructions, or set with set to `X509VerificationFlags.IgnoreEndRevocationUnknown | X509VerificationFlags.IgnoreCertificateAuthorityRevocationUnknown`. + In situations where you can't modify the code, you can restore the previous behavior with one of the following settings: - Set `System.Net.Security.NoRevocationCheckByDefault` AppContext switch to `true`.