From 8ecf6d29cb82837d65bb6abab87ab972cde5f3dc Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Mon, 30 Jun 2025 10:19:02 +0200 Subject: [PATCH] Add breaking change documentation for OpenSSL cryptographic primitives on macOS (#46924) --- docs/core/compatibility/10.0.md | 1 + .../10.0/openssl-macos-unsupported.md | 58 +++++++++++++++++++ docs/core/compatibility/toc.yml | 6 +- 3 files changed, 63 insertions(+), 2 deletions(-) create mode 100644 docs/core/compatibility/cryptography/10.0/openssl-macos-unsupported.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 6b80b5383df7e..067fb31fe6c49 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -52,6 +52,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|-------------------|--------------------| +| [OpenSSL cryptographic primitives aren't supported on macOS](cryptography/10.0/openssl-macos-unsupported.md) | Behavioral change | Preview 6 | | [X500DistinguishedName validation is stricter](cryptography/10.0/x500distinguishedname-validation.md) | Behavioral change | Preview 1 | | [X509Certificate and PublicKey key parameters can be null](cryptography/10.0/x509-publickey-null.md) | Behavioral/source incompatible change | Preview 3 | | [Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE](cryptography/10.0/version-override.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/cryptography/10.0/openssl-macos-unsupported.md b/docs/core/compatibility/cryptography/10.0/openssl-macos-unsupported.md new file mode 100644 index 0000000000000..e40080bb5947e --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/openssl-macos-unsupported.md @@ -0,0 +1,58 @@ +--- +title: "Breaking change: OpenSSL cryptographic primitives aren't supported on macOS" +description: "Learn about the breaking change in .NET 10 where OpenSSL cryptographic primitives are no longer supported on macOS." +ms.date: 06/23/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/46789 +--- +# OpenSSL cryptographic primitives are not supported on macOS + +Starting in .NET 10, OpenSSL-backed cryptographic primitives are no longer supported on macOS. and classes that are specific to OpenSSL, such as , now throw a on macOS. + +## Version introduced + +.NET 10 Preview 6 + +## Previous behavior + +Previously, classes that are specific to OpenSSL, such as , worked on macOS if OpenSSL was available. + + worked on macOS if OpenSSL was available. + +## New behavior + +Classes that are specific to OpenSSL, such as , don't work on macOS even if OpenSSL is available, and a exception is thrown. + + throws a exception. + +## Type of breaking change + +This is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +Support for the OpenSSL-backed primitives originated from .NET Core 1.0, where cryptography on macOS was implemented with OpenSSL. This wasn't ideal because a recent version of OpenSSL doesn't come on macOS, and acquiring and configuring OpenSSL on macOS was troublesome. In the .NET Core 2.0 timeframe, cryptography was moved to Apple's built-in functionality, so cryptographic functionality "just worked" without needing to acquire any additional components. + +The types that are suffixed as `OpenSsl` were left as being implemented by OpenSSL, and doesn't have an implementation in Apple's cryptographic libraries. + +Supporting these OpenSSL-backed primitives on macOS has become more difficult as Apple has made it more difficult to load libraries from certain paths, and it complicates distributing software on macOS. + +## Recommended action + +If you're using OpenSSL-backed primitives without any specific intention of using OpenSSL, the recommendation is to use the factories that provide a macOS implementation: + +* `new DSAOpenSsl(...)` -> `DSA.Create(...)` +* `new ECDiffieHellmanOpenSsl(...)` -> `ECDiffieHellman.Create(...)` +* `new ECDsaOpenSsl(...)` -> `ECDsa.Create(...)` +* `new RSAOpenSsl(...)` -> `RSA.Create(...)` + + has no functional equivalent on macOS. Consider using a different cryptographic primitive, such as , instead. + +## Affected APIs + +* (all constructors) +* (all constructors) +* (all constructors) +* (all constructors) +* (all constructors) +* (entire class) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 362c7454943e3..38d60b7123bb7 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -38,12 +38,14 @@ items: href: core-libraries/10.0/ymm-embedded-rounding.md - name: Cryptography items: + - name: Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE + href: cryptography/10.0/version-override.md + - name: OpenSSL cryptographic primitives not supported on macOS + href: cryptography/10.0/openssl-macos-unsupported.md - name: X500DistinguishedName validation is stricter href: cryptography/10.0/x500distinguishedname-validation.md - name: X509Certificate and PublicKey key parameters can be null href: cryptography/10.0/x509-publickey-null.md - - name: Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE - href: cryptography/10.0/version-override.md - name: Extensions items: - name: "ProviderAliasAttribute moved to Microsoft.Extensions.Logging.Abstractions assembly"