From 74554308874c5aa223670e7aa0fbc1534b0ebf83 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Jun 2025 13:29:27 +0000 Subject: [PATCH 1/4] Initial plan for issue From a5516bec3642ea8aa33354434164698d8a7dce25 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Jun 2025 13:33:23 +0000 Subject: [PATCH 2/4] Add OpenSSL cryptographic primitives breaking change documentation for .NET 10 Preview 6 Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 1 + .../10.0/openssl-macos-unsupported.md | 58 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 61 insertions(+) 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 a3969d610efc7..a7f809520f0cc 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -51,6 +51,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 are not 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..c259399eff615 --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/openssl-macos-unsupported.md @@ -0,0 +1,58 @@ +--- +title: "Breaking change: OpenSSL cryptographic primitives are not 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. Classes that are specific to OpenSSL, such as , and 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 is becoming more difficult as Apple has made it more difficult to load libraries from certain paths, and 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) \ No newline at end of file diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index bd8dd49dadfdc..d5613ae06d4c6 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -36,6 +36,8 @@ items: href: core-libraries/10.0/ymm-embedded-rounding.md - name: Cryptography items: + - name: OpenSSL cryptographic primitives are 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 From c39b6f757e31c6992ed0651bbd9a6a236f325c69 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 23 Jun 2025 16:04:41 +0200 Subject: [PATCH 3/4] human edits --- docs/core/compatibility/10.0.md | 2 +- .../10.0/openssl-macos-unsupported.md | 22 +++++++++---------- docs/core/compatibility/toc.yml | 12 +++++----- 3 files changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index a7f809520f0cc..24f48fd5b92e1 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -51,7 +51,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 are not supported on macOS](cryptography/10.0/openssl-macos-unsupported.md) | Behavioral change | Preview 6 | +| [OpenSSL cryptographic primitives not 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 index c259399eff615..e40080bb5947e 100644 --- a/docs/core/compatibility/cryptography/10.0/openssl-macos-unsupported.md +++ b/docs/core/compatibility/cryptography/10.0/openssl-macos-unsupported.md @@ -1,5 +1,5 @@ --- -title: "Breaking change: OpenSSL cryptographic primitives are not supported on macOS" +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 @@ -7,7 +7,7 @@ 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. Classes that are specific to OpenSSL, such as , and now throw a 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 @@ -15,15 +15,15 @@ Starting in .NET 10, OpenSSL-backed cryptographic primitives are no longer suppo ## Previous behavior -Previously, classes that are specific to OpenSSL such as worked on macOS if OpenSSL was available. +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. +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. + throws a exception. ## Type of breaking change @@ -31,22 +31,22 @@ 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. +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. +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 is becoming more difficult as Apple has made it more difficult to load libraries from certain paths, and complicates distributing software on macOS. +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. +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. + has no functional equivalent on macOS. Consider using a different cryptographic primitive, such as , instead. ## Affected APIs @@ -55,4 +55,4 @@ If you're using OpenSSL-backed primitives without any specific intention of usin * (all constructors) * (all constructors) * (all constructors) -* (entire class) \ No newline at end of file +* (entire class) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index d5613ae06d4c6..93ffc8f2dcd0c 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -36,14 +36,14 @@ items: href: core-libraries/10.0/ymm-embedded-rounding.md - name: Cryptography items: - - name: OpenSSL cryptographic primitives are not supported on macOS + - 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" @@ -1670,12 +1670,14 @@ items: items: - name: .NET 10 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: .NET 9 items: - name: APIs Removed from System.Security.Cryptography.Pkcs netstandard2.0 From f7119b0fc6f9bb5f56ccfdbd778cc47620339521 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Jun 2025 21:14:40 +0000 Subject: [PATCH 4/4] Fix grammar in breaking change title by adding missing verb Co-authored-by: vcsjones <361677+vcsjones@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index e92931a825e8b..765dca5a5fa5d 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -52,7 +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 not supported on macOS](cryptography/10.0/openssl-macos-unsupported.md) | Behavioral change | Preview 6 | +| [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 |