refactor to ISpan interfaces

Author: DeagleGross

src/DataProtection/Abstractions/src/IOptimizedDataProtector.cs renamed to src/DataProtection/Abstractions/src/ISpanDataProtector.cs

@@ -9,20 +9,21 @@
 
 namespace Microsoft.AspNetCore.DataProtection;
 
-#if NET10_0_OR_GREATER
-
 /// <summary>
 /// An interface that can provide data protection services.
 /// Is an optimized version of <see cref="IDataProtector"/>.
 /// </summary>
-public interface IOptimizedDataProtector : IDataProtector
+public interface ISpanDataProtector : IDataProtector
 {
     /// <summary>
-    /// Returns the size of the encrypted data for a given plaintext length.
+    /// Determines the size of the protected data in order to then use <see cref="TryProtect(ReadOnlySpan{byte}, Span{byte}, out int)"/>."/>.
+    /// <br/> Returns the boolean representing if current implementation of data protector supports <see cref="ISpanDataProtector"/> or not.
+    /// If it does not (returns false), then one needs to fallback to <see cref="IDataProtector"/> and use <see cref="IDataProtector.Protect(byte[])"/> and <see cref="IDataProtector.Unprotect(byte[])"/> methods instead.
     /// </summary>
     /// <param name="plainText">The plain text that will be encrypted later</param>
-    /// <returns>The length of the encrypted data</returns>
-    int GetProtectedSize(ReadOnlySpan<byte> plainText);
+    /// <param name="cipherTextLength">The length of the expected cipher text.</param>
+    /// <returns>true, if <see cref="ISpanDataProtector"/> is supported. False if a fallback to <see cref="IDataProtector"/> is required.</returns>
+    bool TryGetProtectedSize(ReadOnlySpan<byte> plainText, out int cipherTextLength);
 
     /// <summary>
     /// Attempts to encrypt and tamper-proof a piece of data.
@@ -33,5 +34,3 @@ public interface IOptimizedDataProtector : IDataProtector
     /// <returns>true if destination is long enough to receive the encrypted data; otherwise, false.</returns>
     bool TryProtect(ReadOnlySpan<byte> plainText, Span<byte> destination, out int bytesWritten);
 }
-
-#endif

src/DataProtection/Abstractions/src/PublicAPI.Unshipped.txt

@@ -1,4 +1,4 @@
 #nullable enable
-Microsoft.AspNetCore.DataProtection.IOptimizedDataProtector
-Microsoft.AspNetCore.DataProtection.IOptimizedDataProtector.GetProtectedSize(System.ReadOnlySpan<byte> plainText) -> int
-Microsoft.AspNetCore.DataProtection.IOptimizedDataProtector.TryProtect(System.ReadOnlySpan<byte> plainText, System.Span<byte> destination, out int bytesWritten) -> bool
+Microsoft.AspNetCore.DataProtection.ISpanDataProtector
+Microsoft.AspNetCore.DataProtection.ISpanDataProtector.TryGetProtectedSize(System.ReadOnlySpan<byte> plainText, out int cipherTextLength) -> bool
+Microsoft.AspNetCore.DataProtection.ISpanDataProtector.TryProtect(System.ReadOnlySpan<byte> plainText, System.Span<byte> destination, out int bytesWritten) -> bool

src/DataProtection/DataProtection/src/AuthenticatedEncryption/ISpanAuthenticatedEncryptor.cs

@@ -9,6 +9,9 @@
 
 namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption;
 
+/// <summary>
+/// Provides an authenticated encryption and decryption routine via a span-based API.
+/// </summary>
 public interface ISpanAuthenticatedEncryptor : IAuthenticatedEncryptor
 {
     /// <summary>

src/DataProtection/DataProtection/src/KeyManagement/KeyRingBasedDataProtector.cs

@@ -21,7 +21,7 @@
 
 namespace Microsoft.AspNetCore.DataProtection.KeyManagement;
 
-internal sealed unsafe class KeyRingBasedDataProtector : IDataProtector, IPersistedDataProtector
+internal sealed unsafe class KeyRingBasedDataProtector : ISpanDataProtector, IPersistedDataProtector
 {
     // This magic header identifies a v0 protected data blob. It's the high 28 bits of the SHA1 hash of
     // "Microsoft.AspNet.DataProtection.KeyManagement.KeyRingBasedDataProtector" [US-ASCII], big-endian.
@@ -92,21 +92,23 @@ public byte[] DangerousUnprotect(byte[] protectedData, bool ignoreRevocationErro
         return retVal;
     }
 
-#if NET10_0_OR_GREATER
-    public int GetProtectedSize(ReadOnlySpan<byte> plainText)
+    public bool TryGetProtectedSize(ReadOnlySpan<byte> plainText, out int cipherTextLength)
     {
+        cipherTextLength = default;
+
         // Get the current key ring to access the encryptor
         var currentKeyRing = _keyRingProvider.GetCurrentKeyRing();
         var defaultEncryptor = currentKeyRing.DefaultAuthenticatedEncryptor;
-        if (defaultEncryptor is not IOptimizedAuthenticatedEncryptor optimizedAuthenticatedEncryptor)
+        if (defaultEncryptor is not ISpanAuthenticatedEncryptor optimizedAuthenticatedEncryptor)
         {
-            throw new NotSupportedException("The current default encryptor does not support optimized protection.");
+            return false;
         }
         CryptoUtil.Assert(optimizedAuthenticatedEncryptor != null, "optimizedAuthenticatedEncryptor != null");
 
         // We allocate a 20-byte pre-buffer so that we can inject the magic header and key id into the return value.
         // See Protect() / TryProtect() for details
-        return _magicHeaderKeyIdSize + optimizedAuthenticatedEncryptor.GetEncryptedSize(plainText.Length);
+        cipherTextLength = _magicHeaderKeyIdSize + optimizedAuthenticatedEncryptor.GetEncryptedSize(plainText.Length);
+        return true;
     }
 
     public bool TryProtect(ReadOnlySpan<byte> plaintext, Span<byte> destination, out int bytesWritten)
@@ -117,11 +119,11 @@ public bool TryProtect(ReadOnlySpan<byte> plaintext, Span<byte> destination, out
             var currentKeyRing = _keyRingProvider.GetCurrentKeyRing();
             var defaultKeyId = currentKeyRing.DefaultKeyId;
             var defaultEncryptor = currentKeyRing.DefaultAuthenticatedEncryptor;
-            if (defaultEncryptor is not IOptimizedAuthenticatedEncryptor optimizedAuthenticatedEncryptor)
+            if (defaultEncryptor is not ISpanAuthenticatedEncryptor spanEncryptor)
             {
                 throw new NotSupportedException("The current default encryptor does not support optimized protection.");
             }
-            CryptoUtil.Assert(optimizedAuthenticatedEncryptor != null, "optimizedAuthenticatedEncryptor != null");
+            CryptoUtil.Assert(spanEncryptor != null, "optimizedAuthenticatedEncryptor != null");
 
             if (_logger.IsDebugLevelEnabled())
             {
@@ -135,15 +137,24 @@ public bool TryProtect(ReadOnlySpan<byte> plaintext, Span<byte> destination, out
             var preBufferSize = _magicHeaderKeyIdSize;
             var postBufferSize = 0;
             var destinationBufferOffsets = destination.Slice(preBufferSize, destination.Length - (preBufferSize + postBufferSize));
-            var success = optimizedAuthenticatedEncryptor.TryEncrypt(plaintext, aad, destinationBufferOffsets, out bytesWritten);
+            var success = spanEncryptor.TryEncrypt(plaintext, aad, destinationBufferOffsets, out bytesWritten);
 
             // At this point: destination := { 000..000 || encryptorSpecificProtectedPayload },
             // where 000..000 is a placeholder for our magic header and key id.
 
             // Write out the magic header and key id
+#if NET10_0_OR_GREATER
             BinaryPrimitives.WriteUInt32BigEndian(destination.Slice(0, sizeof(uint)), MAGIC_HEADER_V0);
             var writeKeyIdResult = defaultKeyId.TryWriteBytes(destination.Slice(sizeof(uint), sizeof(Guid)));
             Debug.Assert(writeKeyIdResult, "Failed to write Guid to destination.");
+#else
+            fixed (byte* pbRetVal = destination)
+            {
+                WriteBigEndianInteger(pbRetVal, MAGIC_HEADER_V0);
+                WriteGuid(&pbRetVal[sizeof(uint)], defaultKeyId);
+            }
+#endif
+
             bytesWritten += _magicHeaderKeyIdSize;
 
             // At this point, destination := { magicHeader || keyId || encryptorSpecificProtectedPayload }
@@ -156,7 +167,6 @@ public bool TryProtect(ReadOnlySpan<byte> plaintext, Span<byte> destination, out
             throw Error.Common_EncryptionFailed(ex);
         }
     }
-#endif
 
     public byte[] Protect(byte[] plaintext)
     {

src/DataProtection/DataProtection/src/PublicAPI.Unshipped.txt

@@ -1,4 +1,4 @@
 #nullable enable
-Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.IOptimizedAuthenticatedEncryptor
-Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.IOptimizedAuthenticatedEncryptor.GetEncryptedSize(int plainTextLength) -> int
-Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.IOptimizedAuthenticatedEncryptor.TryEncrypt(System.ReadOnlySpan<byte> plaintext, System.ReadOnlySpan<byte> additionalAuthenticatedData, System.Span<byte> destination, out int bytesWritten) -> bool
+Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ISpanAuthenticatedEncryptor
+Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ISpanAuthenticatedEncryptor.GetEncryptedSize(int plainTextLength) -> int
+Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ISpanAuthenticatedEncryptor.TryEncrypt(System.ReadOnlySpan<byte> plaintext, System.ReadOnlySpan<byte> additionalAuthenticatedData, System.Span<byte> destination, out int bytesWritten) -> bool

src/DataProtection/DataProtection/test/Microsoft.AspNetCore.DataProtection.Tests/Internal/RoundtripEncryptionHelpers.cs

@@ -4,6 +4,7 @@
 using System;
 using System.Buffers;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.Text;
 using Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption;
 
@@ -28,20 +29,23 @@ public static void AssertTryEncryptTryDecryptParity(IAuthenticatedEncryptor encr
     /// </summary>
     public static void AssertTryEncryptTryDecryptParity(IAuthenticatedEncryptor encryptor, ArraySegment<byte> plaintext, ArraySegment<byte> aad)
     {
+        var spanAuthenticatedEncryptor = encryptor as ISpanAuthenticatedEncryptor;
+        Debug.Assert(spanAuthenticatedEncryptor != null, "ISpanDataProtector is not supported by the encryptor");
+
         // assert "allocatey" Encrypt/Decrypt APIs roundtrip correctly
         byte[] ciphertext = encryptor.Encrypt(plaintext, aad);
         byte[] decipheredtext = encryptor.Decrypt(new ArraySegment<byte>(ciphertext), aad);
         Assert.Equal(plaintext.AsSpan(), decipheredtext.AsSpan());
 
         // assert calculated size is correct
-        var expectedSize = encryptor.GetEncryptedSize(plaintext.Count);
+        var expectedSize = spanAuthenticatedEncryptor.GetEncryptedSize(plaintext.Count);
         Assert.Equal(expectedSize, ciphertext.Length);
 
         // perform TryEncrypt and Decrypt roundtrip - ensures cross operation compatibility
         var cipherTextPooled = ArrayPool<byte>.Shared.Rent(expectedSize);
         try
         {
-            var tryEncryptResult = encryptor.TryEncrypt(plaintext, aad, cipherTextPooled, out var bytesWritten);
+            var tryEncryptResult = spanAuthenticatedEncryptor.TryEncrypt(plaintext, aad, cipherTextPooled, out var bytesWritten);
             Assert.Equal(expectedSize, bytesWritten);
             Assert.True(tryEncryptResult);
 

src/DataProtection/DataProtection/test/Microsoft.AspNetCore.DataProtection.Tests/KeyManagement/KeyRingBasedDataProtectorTests.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Buffers.Binary;
+using System.Diagnostics;
 using System.Globalization;
 using System.Net;
 using System.Security.Cryptography;
@@ -656,7 +657,8 @@ public void GetProtectedSize_TryProtect_CorrectlyEstimatesDataLength_MultipleSce
             newPurpose: "purpose");
 
         // Act - get estimated size
-        int estimatedSize = protector.GetProtectedSize(plaintext);
+        var protectionSizeResult = protector.TryGetProtectedSize(plaintext, out var estimatedSize);
+        Assert.True(protectionSizeResult, "TryGetProtectedSize should succeed");
 
         // verify simple protect works
         var protectedData = protector.Protect(plaintext);
@@ -716,8 +718,9 @@ public void GetProtectedSize_TryProtect_VariousPlaintextSizes(int plaintextSize)
             newPurpose: "purpose");
 
         // Act - get estimated size
-        int estimatedSize = protector.GetProtectedSize(plaintext);
-        
+        var protectionSizeResult = protector.TryGetProtectedSize(plaintext, out var estimatedSize);
+        Assert.True(protectionSizeResult, "TryGetProtectedSize should succeed");
+
         // Act - allocate buffer and try protect
         byte[] destination = new byte[estimatedSize];
         bool success = protector.TryProtect(plaintext, destination, out int bytesWritten);

src/DataProtection/Extensions/src/DataProtectionAdvancedExtensions.cs

@@ -98,7 +98,7 @@ public static string Unprotect(this ITimeLimitedDataProtector protector, string
 
     private sealed class TimeLimitedWrappingProtector : IDataProtector
 #if NET10_0_OR_GREATER
-    , IOptimizedDataProtector
+    , ISpanDataProtector
 #endif
     {
         public DateTimeOffset Expiration;
@@ -131,19 +131,20 @@ public byte[] Unprotect(byte[] protectedData)
         }
 
 #if NET10_0_OR_GREATER
-        public int GetProtectedSize(ReadOnlySpan<byte> plainText)
+        public bool TryGetProtectedSize(ReadOnlySpan<byte> plainText, out int cipherTextLength)
         {
-            if (_innerProtector is IOptimizedDataProtector optimizedDataProtector)
+            if (_innerProtector is ISpanDataProtector optimizedDataProtector)
             {
-                return optimizedDataProtector.GetProtectedSize(plainText);
+                return optimizedDataProtector.TryGetProtectedSize(plainText, out cipherTextLength);
             }
 
-            throw new NotSupportedException("The inner protector does not support optimized data protection.");
+            cipherTextLength = default;
+            return false;
         }
 
         public bool TryProtect(ReadOnlySpan<byte> plainText, Span<byte> destination, out int bytesWritten)
         {
-            if (_innerProtector is IOptimizedDataProtector optimizedDataProtector)
+            if (_innerProtector is ISpanDataProtector optimizedDataProtector)
             {
                 return optimizedDataProtector.TryProtect(plainText, destination, out bytesWritten);
             }

src/DataProtection/Extensions/src/TimeLimitedDataProtector.cs

@@ -18,7 +18,7 @@ namespace Microsoft.AspNetCore.DataProtection;
 /// </summary>
 internal sealed class TimeLimitedDataProtector : ITimeLimitedDataProtector
 #if NET10_0_OR_GREATER
-    , IOptimizedDataProtector
+    , ISpanDataProtector
 #endif
 {
     private const string MyPurposeString = "Microsoft.AspNetCore.DataProtection.TimeLimitedDataProtector.v1";
@@ -134,27 +134,29 @@ byte[] IDataProtector.Unprotect(byte[] protectedData)
     }
 
 #if NET10_0_OR_GREATER
-    public int GetProtectedSize(ReadOnlySpan<byte> plainText)
+    public bool TryGetProtectedSize(ReadOnlySpan<byte> plainText, out int cipherTextLength)
     {
         var dataProtector = GetInnerProtectorWithTimeLimitedPurpose();
-        if (dataProtector is IOptimizedDataProtector optimizedDataProtector)
+        if (dataProtector is ISpanDataProtector optimizedDataProtector)
         {
-            var size = optimizedDataProtector.GetProtectedSize(plainText);
+            var result = optimizedDataProtector.TryGetProtectedSize(plainText, out cipherTextLength);
 
             // prepended the expiration time as a 64-bit UTC tick count takes ExpirationTimeHeaderSize bytes;
             // see Protect(byte[] plaintext, DateTimeOffset expiration) for details
-            return size + ExpirationTimeHeaderSize;
+            cipherTextLength += ExpirationTimeHeaderSize;
+            return result;
         }
 
-        throw new NotSupportedException("The inner protector does not support optimized data protection.");
+        cipherTextLength = default;
+        return false;
     }
 
     public bool TryProtect(ReadOnlySpan<byte> plaintext, Span<byte> destination, out int bytesWritten)
         => TryProtect(plaintext, destination, DateTimeOffset.MaxValue, out bytesWritten);
 
     public bool TryProtect(ReadOnlySpan<byte> plaintext, Span<byte> destination, DateTimeOffset expiration, out int bytesWritten)
     {
-        if (_innerProtector is not IOptimizedDataProtector optimizedDataProtector)
+        if (_innerProtector is not ISpanDataProtector optimizedDataProtector)
         {
             throw new NotSupportedException("The inner protector does not support optimized data protection.");
         }