[API Proposal]: Verify HMAC/KMAC APIs

[vcsjones]

Background and motivation

HMAC values often need to be compared in fixed time. Today, that can be done in two steps, using some API that produces an HMAC like HMACSHA256.HashData, and using CryptographicOperations.FixedTimeEqual.

This can be seen as a bit of a pit of failure because oftentimes folks don't do the fixed time part correctly. They may end up using Linq to compare arrays, or SequenceEqual.

Other frameworks offer a more symmetric signature-like API, where they take the HMAC, the data, and do the MAC over the data and the constant time check for you in a single step.

API Proposal

namespace System.Security.Cryptography;

public partial class HMACMD5 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, byte[] source, byte[] hash);
    
    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, CancellationToken cancellationToken = default);
}

public partial class HMACSHA1 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, byte[] source, byte[] hash);
    
    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, CancellationToken cancellationToken = default);
}

public partial class HMACSHA256 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, byte[] source, byte[] hash);
    
    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, CancellationToken cancellationToken = default);
}

public partial class HMACSHA384 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, byte[] source, byte[] hash);

    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, CancellationToken cancellationToken = default);
}

public partial class HMACSHA512 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, byte[] source, byte[] hash);
    
    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, CancellationToken cancellationToken = default);
}

public partial class HMACSHA3_256 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, byte[] source, byte[] hash);
    
    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, CancellationToken cancellationToken = default);
}

public partial class HMACSHA3_384 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, byte[] source, byte[] hash);
    
    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, CancellationToken cancellationToken = default);
}

public partial class HMACSHA3_512 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, byte[] source, byte[] hash);
    
    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, CancellationToken cancellationToken = default);
}

public partial class Kmac128 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash, ReadOnlySpan<byte> customizationString = default);
    public static bool Verify(byte[] key, byte[] source, byte[] hash, byte[]? customizationString = null);

    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash, ReadOnlySpan<byte> customizationString = default);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash, byte[] customizationString = null);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, byte[] customizationString = null, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, ReadOnlyMemory<byte> customizationString = default, CancellationToken cancellationToken = default);

    public bool VerifyCurrentHash(ReadOnlySpan<byte> hash);
    public bool VerifyCurrentHash(byte[] hash);

    public bool VerifyHashAndReset(ReadOnlySpan<byte> hash);
    public bool VerifyHashAndReset(byte[] hash);
}

public partial class Kmac256 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash, ReadOnlySpan<byte> customizationString = default);
    public static bool Verify(byte[] key, byte[] source, byte[] hash, byte[]? customizationString = null);

    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash, ReadOnlySpan<byte> customizationString = default);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash, byte[] customizationString = null);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, byte[] customizationString = null, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, ReadOnlyMemory<byte> customizationString = default, CancellationToken cancellationToken = default);

    public bool VerifyCurrentHash(ReadOnlySpan<byte> hash);
    public bool VerifyCurrentHash(byte[] hash);

    public bool VerifyHashAndReset(ReadOnlySpan<byte> hash);
    public bool VerifyHashAndReset(byte[] hash);
}

public partial class KmacXof128 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash, ReadOnlySpan<byte> customizationString = default);
    public static bool Verify(byte[] key, byte[] source, byte[] hash, byte[]? customizationString = null);

    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash, ReadOnlySpan<byte> customizationString = default);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash, byte[] customizationString = null);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, byte[] customizationString = null, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, ReadOnlyMemory<byte> customizationString = default, CancellationToken cancellationToken = default);

    public bool VerifyCurrentHash(ReadOnlySpan<byte> hash);
    public bool VerifyCurrentHash(byte[] hash);

    public bool VerifyHashAndReset(ReadOnlySpan<byte> hash);
    public bool VerifyHashAndReset(byte[] hash);
}

public partial class KmacXof256 {
    public static bool Verify(ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash, ReadOnlySpan<byte> customizationString = default);
    public static bool Verify(byte[] key, byte[] source, byte[] hash, byte[]? customizationString = null);

    public static bool Verify(ReadOnlySpan<byte> key, System.IO.Stream source, ReadOnlySpan<byte> hash, ReadOnlySpan<byte> customizationString = default);
    public static bool Verify(byte[] key, System.IO.Stream source, byte[] hash, byte[] customizationString = null);
    public static bool VerifyAsync(byte[] key, System.IO.Stream source, byte[] hash, byte[] customizationString = null, CancellationToken cancellationToken = default);
    public static bool VerifyAsync(ReadOnlyMemory<byte> key, System.IO.Stream source, ReadOnlyMemory<byte> hash, ReadOnlyMemory<byte> customizationString = default, CancellationToken cancellationToken = default);

    public bool VerifyCurrentHash(ReadOnlySpan<byte> hash);
    public bool VerifyCurrentHash(byte[] hash);

    public bool VerifyHashAndReset(ReadOnlySpan<byte> hash);
    public bool VerifyHashAndReset(byte[] hash);
}

public partial class IncrementalHash {
    public bool VerifyCurrentHash(ReadOnlySpan<byte> hash);
    public bool VerifyCurrentHash(byte[] hash);

    public bool VerifyHashAndReset(ReadOnlySpan<byte> hash);
    public bool VerifyHashAndReset(byte[] hash);
}

public partial class CryptographicOperations {
    public static bool VerifyHmac(HashAlgorithmName hashAlgorithm, ReadOnlySpan<byte> key, ReadOnlySpan<byte> source, ReadOnlySpan<byte> hash);
    public static bool VerifyHmac(HashAlgorithmName hashAlgorithm, byte[] key, byte[] source, byte[] hash);

    public static bool VerifyHmac(HashAlgorithmName hashAlgorithm, ReadOnlySpan<byte> key, Stream source, ReadOnlySpan<byte> hash);
    public static bool VerifyHmac(HashAlgorithmName hashAlgorithm, byte[] key, Stream source, byte[] hash);
    
    public static bool VerifyHmacAsync(HashAlgorithmName hashAlgorithm, ReadOnlyMemory<byte> key, Stream source, ReadOnlyMemory<byte> hash, CancellationToken cancellationToken = default);
    public static bool VerifyHmacAsync(HashAlgorithmName hashAlgorithm, byte[] key, Stream source, byte[] hash, CancellationToken cancellationToken = default);
}

API Usage

Similar to the HashData methods of each respective class, however it accepts an input MAC to verify against, which will be done with CryptographicOperations.

Alternative Designs

• For similar reasoning as in [API Proposal]: Clone for IncrementalHash and KMAC #103170, no instance methods on HashAlgorithm is proposed.
• I don't love that these are called VerifyHash. VerifyHmac or something would be better. However we tend to favor consistency, and this is more consistent with the existing method names.
• There is no clear need for these with plain hashes. If there is a compelling reason to add them, we can.

Risks

It is yet another way to do H/KMAC things.

[dotnet-policy-service]

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

[vcsjones]

Some implementation notes, since that may impact the design.

1. If the lengths do not match, then we will early exit. That is, if the hash or expected MAC is not the actual size of that the MAC function produces, it will not perform a comparison. This is similar to what FixedTimeEquals does now. All this does is allow an attacker to learn something they already knew (that the input is not the size of the HMAC).
2. For KMAC, the length of the hash is the length to produce. Since KMAC is built on a XOF, the produced KMAC will be whatever the size of the input MAC is. So it will always operate on equal-sized MAC values.

The first will be noted in the <remarks> section as appropriate.

[blowdart]

Naming: As the current classes have Hash as a method and not, for example ComputeHash.

Do we need the word Hash in VerifyHash? Would Verify not be more in keeping with the single verb methods we have now?

[necoc-yaotl]

Naming: As the current classes have Hash as a method and not, for example ComputeHash.

Do we need the word Hash in VerifyHash? Would Verify not be more in keeping with the single verb methods we have now?

+1 to @blowdart 's comment. Verify would probably work better, or if you prefer to be explicit, VerifyMAC.

BTW. Great feature suggestion. I have always considered that since we already had a constant time comparison function (CryptographicOperations.FixedTimeEqual) this was not a problem without realizing that even though it is available, it is easy to make mistakes & people may often use a non-constant comparison method.

[bartonjs]

If the lengths do not match, then we will early exit.

For the VerifyHashAndReset methods that'll either need to throw, or still call reset. (It says And Reset, so it can't cleanly exit without resetting).

/* InvalidOperation unless was created with `CreateHMAC` */     public bool VerifyCurrentHash(ReadOnlySpan<byte> hash);

I'm not sure that fills me with happiness. If the method name contained HMAC, sure. Otherwise, I'd just let it slide through for non-keyed hashes as emergent behavior... but not let it be used as a reason why we need it on the unkeyed hash types as static operations.

Do we need the word Hash in VerifyHash?

We do on IncrementalHash, where the verbs are GetHash... and GetCurrentHash, so the balancing there is VerifyHash... and VerifyCurrentHash (or, if we want, VerifyHmac...)

On CryptographicOperations the methods are HmacData, since there's no context, so VerifyHmac seems to be the best name there.

For the on-algorithm static operations, ComputeHash is already a name that's in use, but we had to decide to accept Hash as a verb so we could have the static versions next to the instance versions that already existed. On those, maybe Verify is better than VerifyHash, since if we ever felt compelled to square off this triangle we'd need a naming pattern that works.

So that'd be

incremental.VerifyHmacAndReset(...);
CryptographicOperations.VerifyHmac(...);
HMACSHA256.Verify(...);

Each would be locally consistent, with a flavor (but not actuality) of global consistency.

[vcsjones]

For the VerifyHashAndReset methods that'll either need to throw, or still call reset. (It says And Reset, so it can't cleanly exit without resetting).

I am fine with throwing, too. Agree it makes more sense.

I'm not sure that fills me with happiness. If the method name contained HMAC, sure. Otherwise, I'd just let it slide through for non-keyed hashes as emergent behavior... but not let it be used as a reason why we need it on the unkeyed hash types as static operations.

I am fine with letting it “just work” so long as that last sentence holds true.

Each would be locally consistent

KMAC is the interesting ones here, because their API shape is basically “IncrementalHash but with one-shots”. Should KMAC have the suffix, or not?

[vcsjones]

Update proposal with what seems to be a reasonable interpretation of the suggestions.