[Breaking change]: .NET 10 Preview 6 drops support for OpenSSL Cryptographic Primitives on macOS

[vcsjones]

Description

.NET 10 will stop supporting the use of OpenSSL on macOS to enable some cryptographic primitive classes.

Version

.NET 10 Preview 6

Previous behavior

Previously, some classes that specific to OpenSSL such as RSAOpenSsl would work on macOS if OpenSSL was available.

AesCcm would work on macOS if OpenSSL was available.

New behavior

Classes that specific to OpenSSL such as RSAOpenSsl will not work on macOS even if OpenSSL was available, and a PlatformNotSupportedException exception will be thrown.

AesCcm will throw a PlatformNotSupportedException exception.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

Support for the OpenSSL-backed primitives originates from .NET Core 1.0, where cryptography on macOS was implemented with OpenSSL. This was not ideal because a recent version OpenSSL does not 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 AesCcm does not 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 are 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(...)

AesCcm has no functional equivalent on macOS. Consider using a different cryptographic primitive such as AesGcm instead.

Feature area

Cryptography

Affected APIs

• System.Security.Cryptography.AesCcm (all constructors)
• System.Security.Cryptography.DSAOpenSsl (all constructors)
• System.Security.Cryptography.ECDiffieHellmanOpenSsl (all constructors)
• System.Security.Cryptography.ECDsaOpenSsl (all constructors)
• System.Security.Cryptography.RSAOpenSsl (all constructors)
• System.Security.Cryptography.SafeEvpPKeyHandle (entire class)

[vcsjones]

/cc @bartonjs for review.

[bartonjs]

Edited for grammar with an edit of editing.

-`AesCcm` will throw `PlatformNotSupportedException` exception will be thrown.
+`AesCcm` will throw a `PlatformNotSupportedException` exception.

Otherwise, LGTM.