CryptographicOperations (#561)

Author: SimonCropp

api_list.include.md

@@ -1461,6 +1461,40 @@
    * Note: When growing, new elements are default(T); the BCL exposes uninitialized data.
 
 
+#### CryptographicOperations
+
+ * `bool FixedTimeEquals(ReadOnlySpan<byte>, byte)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.fixedtimeequals?view=net-11.0#system-security-cryptography-cryptographicoperations-fixedtimeequals(system-readonlyspan((system-byte))-system-byte))
+   * Note: Best-effort constant-time comparison; a managed loop cannot offer the same guarantees as the BCL intrinsic.
+ * `bool FixedTimeEquals(ReadOnlySpan<byte>, ReadOnlySpan<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.fixedtimeequals?view=net-11.0#system-security-cryptography-cryptographicoperations-fixedtimeequals(system-readonlyspan((system-byte))-system-readonlyspan((system-byte))))
+   * Note: Best-effort constant-time comparison; a managed loop cannot offer the same guarantees as the BCL intrinsic.
+ * `byte[] HashData(HashAlgorithmName, byte[])` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hashdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hashdata(system-security-cryptography-hashalgorithmname-system-byte()))
+ * `int HashData(HashAlgorithmName, ReadOnlySpan<byte>, Span<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hashdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hashdata(system-security-cryptography-hashalgorithmname-system-readonlyspan((system-byte))-system-span((system-byte))))
+ * `byte[] HashData(HashAlgorithmName, ReadOnlySpan<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hashdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hashdata(system-security-cryptography-hashalgorithmname-system-readonlyspan((system-byte))))
+ * `int HashData(HashAlgorithmName, Stream, Span<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hashdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hashdata(system-security-cryptography-hashalgorithmname-system-io-stream-system-span((system-byte))))
+ * `byte[] HashData(HashAlgorithmName, Stream)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hashdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hashdata(system-security-cryptography-hashalgorithmname-system-io-stream))
+ * `ValueTask<byte[]> HashDataAsync(HashAlgorithmName, Stream, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hashdataasync?view=net-11.0#system-security-cryptography-cryptographicoperations-hashdataasync(system-security-cryptography-hashalgorithmname-system-io-stream-system-threading-cancellationtoken))
+ * `ValueTask<int> HashDataAsync(HashAlgorithmName, Stream, Memory<byte>, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hashdataasync?view=net-11.0#system-security-cryptography-cryptographicoperations-hashdataasync(system-security-cryptography-hashalgorithmname-system-io-stream-system-memory((system-byte))-system-threading-cancellationtoken))
+ * `byte[] HmacData(HashAlgorithmName, byte[], byte[])` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hmacdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hmacdata(system-security-cryptography-hashalgorithmname-system-byte()-system-byte()))
+ * `byte[] HmacData(HashAlgorithmName, byte[], Stream)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hmacdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hmacdata(system-security-cryptography-hashalgorithmname-system-byte()-system-io-stream))
+ * `int HmacData(HashAlgorithmName, ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hmacdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hmacdata(system-security-cryptography-hashalgorithmname-system-readonlyspan((system-byte))-system-readonlyspan((system-byte))-system-span((system-byte))))
+ * `byte[] HmacData(HashAlgorithmName, ReadOnlySpan<byte>, ReadOnlySpan<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hmacdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hmacdata(system-security-cryptography-hashalgorithmname-system-readonlyspan((system-byte))-system-readonlyspan((system-byte))))
+ * `int HmacData(HashAlgorithmName, ReadOnlySpan<byte>, Stream, Span<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hmacdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hmacdata(system-security-cryptography-hashalgorithmname-system-readonlyspan((system-byte))-system-io-stream-system-span((system-byte))))
+ * `byte[] HmacData(HashAlgorithmName, ReadOnlySpan<byte>, Stream)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hmacdata?view=net-11.0#system-security-cryptography-cryptographicoperations-hmacdata(system-security-cryptography-hashalgorithmname-system-readonlyspan((system-byte))-system-io-stream))
+ * `ValueTask<byte[]> HmacDataAsync(HashAlgorithmName, byte[], Stream, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hmacdataasync?view=net-11.0#system-security-cryptography-cryptographicoperations-hmacdataasync(system-security-cryptography-hashalgorithmname-system-byte()-system-io-stream-system-threading-cancellationtoken))
+ * `ValueTask<byte[]> HmacDataAsync(HashAlgorithmName, ReadOnlyMemory<byte>, Stream, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hmacdataasync?view=net-11.0#system-security-cryptography-cryptographicoperations-hmacdataasync(system-security-cryptography-hashalgorithmname-system-readonlymemory((system-byte))-system-io-stream-system-threading-cancellationtoken))
+ * `ValueTask<int> HmacDataAsync(HashAlgorithmName, ReadOnlyMemory<byte>, Stream, Memory<byte>, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.hmacdataasync?view=net-11.0#system-security-cryptography-cryptographicoperations-hmacdataasync(system-security-cryptography-hashalgorithmname-system-readonlymemory((system-byte))-system-io-stream-system-memory((system-byte))-system-threading-cancellationtoken))
+ * `bool TryHashData(HashAlgorithmName, ReadOnlySpan<byte>, Span<byte>, int)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.tryhashdata?view=net-11.0)
+ * `bool TryHmacData(HashAlgorithmName, ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>, int)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.tryhmacdata?view=net-11.0)
+ * `bool VerifyHmac(HashAlgorithmName, byte[], byte[], byte[])` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.verifyhmac?view=net-11.0#system-security-cryptography-cryptographicoperations-verifyhmac(system-security-cryptography-hashalgorithmname-system-byte()-system-byte()-system-byte()))
+ * `bool VerifyHmac(HashAlgorithmName, byte[], Stream, byte[])` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.verifyhmac?view=net-11.0#system-security-cryptography-cryptographicoperations-verifyhmac(system-security-cryptography-hashalgorithmname-system-byte()-system-io-stream-system-byte()))
+ * `bool VerifyHmac(HashAlgorithmName, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.verifyhmac?view=net-11.0#system-security-cryptography-cryptographicoperations-verifyhmac(system-security-cryptography-hashalgorithmname-system-readonlyspan((system-byte))-system-readonlyspan((system-byte))-system-readonlyspan((system-byte))))
+ * `bool VerifyHmac(HashAlgorithmName, ReadOnlySpan<byte>, Stream, ReadOnlySpan<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.verifyhmac?view=net-11.0#system-security-cryptography-cryptographicoperations-verifyhmac(system-security-cryptography-hashalgorithmname-system-readonlyspan((system-byte))-system-io-stream-system-readonlyspan((system-byte))))
+ * `ValueTask<bool> VerifyHmacAsync(HashAlgorithmName, byte[], Stream, byte[], CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.verifyhmacasync?view=net-11.0#system-security-cryptography-cryptographicoperations-verifyhmacasync(system-security-cryptography-hashalgorithmname-system-byte()-system-io-stream-system-byte()-system-threading-cancellationtoken))
+ * `ValueTask<bool> VerifyHmacAsync(HashAlgorithmName, ReadOnlyMemory<byte>, Stream, ReadOnlyMemory<byte>, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.verifyhmacasync?view=net-11.0#system-security-cryptography-cryptographicoperations-verifyhmacasync(system-security-cryptography-hashalgorithmname-system-readonlymemory((system-byte))-system-io-stream-system-readonlymemory((system-byte))-system-threading-cancellationtoken))
+ * `void ZeroMemory(Span<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.cryptographicoperations.zeromemory?view=net-11.0)
+   * Note: Best-effort zeroing; unlike the BCL intrinsic the JIT may elide the clear if the buffer is not observed afterwards.
+
+
 #### Utf16
 
  * `int IndexOfInvalidSubsequence(ReadOnlySpan<char>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.text.unicode.utf16.indexofinvalidsubsequence?view=net-11.0)

src/ApiBuilderTests/BuildApiTest.cs

@@ -19,6 +19,7 @@ public Task RunWithRoslyn()
         WriteHelper("Lock", writer, ref count);
         WriteHelper(nameof(KeyValuePair), writer, ref count);
         WriteHelper("CollectionsMarshal", writer, ref count);
+        WriteHelper("CryptographicOperations", writer, ref count);
         WriteHelper("Utf16", writer, ref count);
         WriteType(nameof(TaskCompletionSource), writer, ref count);
         WriteType(nameof(UnreachableException), writer, ref count);

src/Consume/Consume.cs

@@ -416,6 +416,53 @@ void MD5Usage()
         MD5.HashDataAsync(source: null!, destination: memory);
         MD5.HashDataAsync(source: null!, destination: memory, cancellationToken: CancellationToken.None);
 #endif
+#endif
+    }
+
+    void CryptographicOperationsUsage()
+    {
+        var name = HashAlgorithmName.SHA256;
+
+        CryptographicOperations.HashData(name, (byte[]) null!);
+        CryptographicOperations.HashData(name, (Stream) null!);
+        CryptographicOperations.HmacData(name, (byte[]) null!, (byte[]) null!);
+        CryptographicOperations.HmacData(name, (byte[]) null!, (Stream) null!);
+        CryptographicOperations.VerifyHmac(name, (byte[]) null!, (byte[]) null!, (byte[]) null!);
+        CryptographicOperations.VerifyHmac(name, (byte[]) null!, (Stream) null!, (byte[]) null!);
+#if FeatureValueTask
+        CryptographicOperations.HashDataAsync(name, (Stream) null!, CancellationToken.None);
+        CryptographicOperations.HmacDataAsync(name, (byte[]) null!, (Stream) null!, CancellationToken.None);
+        CryptographicOperations.VerifyHmacAsync(name, (byte[]) null!, (Stream) null!, (byte[]) null!, CancellationToken.None);
+#endif
+#if FeatureMemory
+        Span<byte> span = default;
+        ReadOnlySpan<byte> readOnlySpan = default;
+        Memory<byte> memory = default;
+        ReadOnlyMemory<byte> readOnlyMemory = default;
+
+        CryptographicOperations.FixedTimeEquals(readOnlySpan, readOnlySpan);
+        CryptographicOperations.FixedTimeEquals(readOnlySpan, (byte) 0);
+        CryptographicOperations.ZeroMemory(span);
+        CryptographicOperations.HashData(name, readOnlySpan);
+        CryptographicOperations.HashData(name, readOnlySpan, span);
+        CryptographicOperations.HashData(name, (Stream) null!, span);
+        CryptographicOperations.TryHashData(name, readOnlySpan, span, out _);
+        CryptographicOperations.HmacData(name, readOnlySpan, readOnlySpan);
+        CryptographicOperations.HmacData(name, readOnlySpan, readOnlySpan, span);
+        CryptographicOperations.HmacData(name, readOnlySpan, (Stream) null!);
+        CryptographicOperations.HmacData(name, readOnlySpan, (Stream) null!, span);
+        CryptographicOperations.TryHmacData(name, readOnlySpan, readOnlySpan, span, out _);
+        CryptographicOperations.VerifyHmac(name, readOnlySpan, readOnlySpan, readOnlySpan);
+        CryptographicOperations.VerifyHmac(name, readOnlySpan, (Stream) null!, readOnlySpan);
+#if FeatureValueTask
+        CryptographicOperations.HashDataAsync(name, (Stream) null!, memory);
+        CryptographicOperations.HashDataAsync(name, (Stream) null!, memory, CancellationToken.None);
+        CryptographicOperations.HmacDataAsync(name, readOnlyMemory, (Stream) null!);
+        CryptographicOperations.HmacDataAsync(name, readOnlyMemory, (Stream) null!, CancellationToken.None);
+        CryptographicOperations.HmacDataAsync(name, readOnlyMemory, (Stream) null!, memory, CancellationToken.None);
+        CryptographicOperations.VerifyHmacAsync(name, readOnlyMemory, (Stream) null!, readOnlyMemory);
+        CryptographicOperations.VerifyHmacAsync(name, readOnlyMemory, (Stream) null!, readOnlyMemory, CancellationToken.None);
+#endif
 #endif
     }