Missing HMAC breaking change

[ealsur]

Please see this thread: Azure/azure-cosmos-dotnet-v3#1865 (comment)

HMAC is also a breaking change that should be listed in the Cryptography section.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 5f68af3a-3848-48ef-c24b-cf33b880ca1b
• Version Independent ID: 580c061d-20e5-248c-a24f-7a48a684c7e3
• Content: Breaking changes, version 3.1 to 5.0 - .NET Core
• Content Source: docs/core/compatibility/3.1-5.0.md
• Product: dotnet-core
• GitHub Login: @gewarren
• Microsoft Alias: gewarren

[gewarren]

Related to #20143. But wouldn't HMAC be covered by the statement in "Affected APIs":

All System.Security.Cryptography APIs except the following:

System.Security.Cryptography.RandomNumberGenerator
System.Security.Cryptography.IncrementalHash
System.Security.Cryptography.SHA1
System.Security.Cryptography.SHA256
System.Security.Cryptography.SHA384
System.Security.Cryptography.SHA512
System.Security.Cryptography.SHA1Managed
System.Security.Cryptography.SHA256Managed
System.Security.Cryptography.SHA384Managed
System.Security.Cryptography.SHA512Managed

Would it be better to explicitly list each affected API?

[ealsur]

In the case our users reported, it was System.Security.Cryptography.HMACSHA256.

From that thread:

The SHA* hash algorithms were added back in RC2 as a special exception to policy. That exception did not extend code dealing with secrets so HMAC computations were not included. Given that, there isn't anything we can do on the runtime side either. I'm not familiar enough to be sure but if there is a way to supply a custom asynchronous authentication provider you might be able to use the Blazor interop code to call into the browser and use crypto.sign to generate your authentication code. Unfortunately it won't be possible to use System.Security to do it in net5.0.

[gewarren]

Okay, I guess I'm not sure what is missing from the doc then, unless you think it should explicitly list each affected API instead of the APIs that aren't affected.

[GrabYourPitchforks]

I agree with @gewarren's assessment. The docs seem clear on this: if it's in System.Security.Cryptography, it'll throw PNSE at runtime unless it's on that list of things that have been special-cased.

[GrabYourPitchforks]

Here's the error text that's presented to the user as part of the PNSE:

System.Security.Cryptography.Algorithms is not supported on this platform.

Maybe this error text needs to be more descriptive? Maybe it needs to include a link to the breaking change notification?

[ealsur]

@GrabYourPitchforks I see now what you mean, I believe that I got the wrong meaning of the Affected APIs section, totally missed the "except" in the text and thought the list was of the APIs that were broken.