HMAC one-shot methods

[vcsjones]

Background and Motivation

In #17590 we added one-shot methods for hashing. It might be worth considering similar methods on the HMAC classes to provide some API parity, and to offer the same benefits as one-shot hash: straight forward API, no stateful object allocation, etc.

Proposed API

namespace System.Security.Cryptography {
    public partial class HMACMD5 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }

    public partial class HMACSHA1 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }

    public partial class HMACSHA256 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }

    public partial class HMACSHA384 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }

    public partial class HMACSHA512 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }
}

The API is the same as #17590 on the appropriate classes, with the addition of a key parameter.

[Dotnet-GitSync-Bot]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[vcsjones]

@bartonjs @krwq

[ghost]

Tagging subscribers to this area: @bartonjs, @vcsjones, @krwq
See info in area-owners.md if you want to be subscribed.

[GrabYourPitchforks]

What's wrong with using the method name HashData, same as we added on the other types? "Hashing" is still the appropriate term. It just happens to be keyed rather than unkeyed.

[vcsjones]

What's wrong with using the method name HashData

Nothing. I just thought Hash was not exactly descriptive, but maybe I thought about it too hard. We can keep the name too.

[SteveSyfuhs]

HashData would be preferred speaking as a consumer of them. It is the method I'd logically look for first when trying to figure out how to make it work.

[vcsjones]

Okay, sounds like I am the outlier on wanting a different name; I have restored the name from the other proposal.

[vcsjones]

vcsjones closed this

Doh.

[bartonjs]

My only concern with HashData(key, data) is that it doesn't necessarily follow that the first argument is the key (and, since HMAC doesn't require block-sized keys, there's not a strong feedback that you got it wrong).

As it is, one has to think about HashData(a) vs HashData(a, b) for which of a/b is the key (cognative overload with the same identifier).

Specs seem to be all over the place.

• The HMAC RFC doesn't actually define a function syntax, and they use H(a, b) to mean H(a.Concat(b))
• The old CBC-MAC standard (FIPS 113) also doesn't define a syntax, it just names the output (DAC, instead of MAC, even though it acknowledged they meant the same thing).
• At least one paper uses MAC_a(x), which doesn't help our ordering problem.
• The NIST glossary, via NIST SP 800-56A (rev 2), defines MAC(MacKey, MacData), which is what I (and probably all of us crypto-nerds) think of for the general application of the problem.

So, for a thing that uses a key and an algorithm over data, I think the verb is "Authenticate"... though that does imply a boolean response (to me): public static byte[] AuthenticateData(key, data).

NIST SP 800-56A does define the output of that function (after being run through a truncator, if needed) MacTag. So we could use TagData/GetTag/ComputeTag, since any of these imply (to me) that they are "tagging" something, producing "a tag"... and then I need to understand what that means.

Alternatively, MacData, though it requires we introduce "Mac" as a verb, and slightly looks like "son-of-(LCDR )Data". Y'know, little Lal MacData?

[vcsjones]

Oh good someone who can articulate what is in my head clearly, much appreciated.

I would personally prefer MacData, as evidence of the original proposal. On the other hand...

I (and probably all of us crypto-nerds) think of for the general application of the problem

I can be persuaded that generally, most of the time the audience may not be crypto nerds that go spelunking through NIST papers and MacData terminology is "technically correct, the best kind of correct". That combined with the platform has used the nomenclature (keyed) "hashing" for HMAC since forever, maybe HashData, or KeyedHashData might be more acceptable. (The latter is perhaps redundant since it is off of an HMAC class).

I think the verb is "Authenticate"

In the case of MACs, I tend to think of it as symmetric signing, so if I was forced to pick a verb, it would be "sign" to produce the signature, and "authenticate" would be "verify" that returns a bool. I shied away from mentioning this or considering Sign as a name since nowhere in the platform is HMAC explained as symmetric signing. (WebCrypto is one notable place that does).

I'm in favor or MacData or similar for since it feels right to me, but also in favor of HashData since I think that is closer to what people would expect and understand based on the current framework.

[vcsjones]

@bartonjs What's remaining to move this forward? It seems like the only hitch is the name of the members. Given the discussion, it seems like:

1. HashData - it's still hashing, just not keyed hashing. This is also consistent (unsure if that is good or bad...) with the non-keyed hash methods.
2. MacData - Alternative name to make it clear it's a mac, but perhaps redundant given the methods are off HMAC classes.
3. AuthenticateData - We don't really use "authenticate" anywhere within Libraries to mean a cryptographic hmac. Some precedent with the AesGcm class.
4. SignData - thought of as a "symmetric sign". Not my favorite but thought I would list it.

[bartonjs]

Video

Looks good as proposed.

namespace System.Security.Cryptography {
    public partial class HMACMD5 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }

    public partial class HMACSHA1 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }

    public partial class HMACSHA256 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }

    public partial class HMACSHA384 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }

    public partial class HMACSHA512 {
        public static byte[] HashData(byte[] key, byte[] source) => throw null;
        public static byte[] HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source) => throw null;
        public static int HashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination) => throw null;
        public static bool TryHashData(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten) => throw null;
    }
}

[teo-tsirpanis]

Shouldn't this be added in "What's new in .NET 6 Preview 5"?

[bartonjs]

Shouldn't this be added in "What's new in .NET 6 Preview 5"?

No, Preview 5 closed for new features about a week ago, this'll be new in Preview 6.