.NET Core 2.0 Cryptography uses Apple Security Framework on macOS

[richlander]

.NET Core 2.0 Cryptography uses Apple Security Framework on macOS

Summary

As part of the .NET Core 2.0 release, .NET Core cryptography APIs were changed to use the Apple Security Framework when running on macOS (10.12 and later versions). .NET Core 1.x uses OpenSSL on macOS/OS X (10.11 and later versions).

There were two challenges with using OpenSSL on macOS that motivated this change:

• Apple deprecated the use of OpenSSL on macOS (see the OpenSSL section).
• OpenSSL is not part of the macOS operating system and must be separately installed via Homebrew. This dependency, which was the only .NET Core dependency on macOS, added friction to using .NET Core on macOS.

.NET Core now uses the cryptography API that is offered for each operating system:

• Apple Security Framework on macOS
• OpenSSL on Linux
• CNG on Windows

Details

• dotnet/corefx #9394
• dotnet/corefx #17011
• Cross-Platform Cryptography

Impact

All cryptography functionality is now provided by the Apple Security Framework. Only types whose name includes "OpenSsl", such as RSAOpenSsl, will continue to use OpenSSL on macOS. When using these APIs, OpenSSL needs to be installed separately via Homebrew since .NET Core doesn't install it.

The following types now use the Apple Security framework:

• RSA, DSA, and ECDSA use SecKeyRef
  • No new public interop types were added with this change, they can come in the future.
  • Apple doesn't allow new DSA keys to be generated. This is import/certs only.
• X509Certificate and X509Certificate2 use SecCertificateRef, and SecIdentityRef
• X509Chain uses SecTrustRef
• X509Store uses Keychain (CU\My, LM\My), SecTrustSettings (CU/LM Root/Disallowed)
• SslStream uses Secure Transport (SslContextRef)

There are some cryptography operations that were supported by OpenSSL on macOS that are no longer supported with the new implementation, due to the functionality provided by the Apple Security Framework. See the Cross-Platform Cryptography document to learn about cryptography support per operating system.

The following types/scenarios have been affected by this change:

• HTTPS: libcurl
  • Understanding that libcurl+openssl is special has been removed.
• OID lookup moves to a fixed set of data due to lack of exposed platform API.

[terrajobst]

Reopening according to process.