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..a012c0e6dc9e9 --- /dev/null +++ b/docs/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default.md @@ -0,0 +1,66 @@ +--- +title: "Breaking change - HttpClient/SslStream default certificate revocation check mode changed 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` + +The default values of and have changed from `NoCheck` to `Online`. This change enhances security and makes the behavior consistent with . + +## Version introduced + +.NET 10 Preview 6 + +## Previous behavior + +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 values of and are , meaning revocation status of peer certificates are checked online by default. + +## Type of breaking change + +This change 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 explicitly: + +```csharp +var clientOptions = new SslClientAuthenticationOptions +{ + TargetHost = "example.com", + CertificateRevocationCheckMode = X509RevocationMode.NoCheck +}; + +var serverOptions = new SslServerAuthenticationOptions +{ + ServerCertificate = serverCertificate, + CertificateRevocationCheckMode = X509RevocationMode.NoCheck +}; +``` + +> [!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`. +- Set `DOTNET_SYSTEM_NET_SECURITY_NOREVOCATIONCHECKBYDEFAULT` environment variable to `true`. + +## Affected APIs + +- +- +- +- +- (when using either or ) +- (when using either or ) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index bd8dd49dadfdc..5bd32a281f55d 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