Use SHA384 and make key more explicit (#6237)

* Minimal change in AIJsonUtilities from SHA256 to SHA384

* Update GetCacheKey API to have explicit messages/options params

The point of this is to make it easier and more reliable for people overriding the logic to obtain specific values from messages/options to include in cache key without having to search through an opaque list of `object` values.

Author: SteveSandersonMS

src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.cs

@@ -90,7 +90,7 @@ public static string HashDataToString(ReadOnlySpan<object?> values, JsonSerializ
 
         // For cases where the hash may be used as a cache key, we rely on collision resistance for security purposes.
         // If a collision occurs, we'd serve a cached LLM response for a potentially unrelated prompt, leading to information
-        // disclosure. Use of SHA256 is an implementation detail and can be easily swapped in the future if needed, albeit
+        // disclosure. Use of SHA384 is an implementation detail and can be easily swapped in the future if needed, albeit
         // invalidating any existing cache entries.
 #if NET
         IncrementalHashStream? stream = IncrementalHashStream.ThreadStaticInstance;
@@ -107,7 +107,7 @@ public static string HashDataToString(ReadOnlySpan<object?> values, JsonSerializ
             stream = new();
         }
 
-        Span<byte> hashData = stackalloc byte[SHA256.HashSizeInBytes];
+        Span<byte> hashData = stackalloc byte[SHA384.HashSizeInBytes];
         try
         {
             foreach (object? value in values)
@@ -133,8 +133,8 @@ public static string HashDataToString(ReadOnlySpan<object?> values, JsonSerializ
             JsonSerializer.Serialize(stream, value, jti);
         }
 
-        using var sha256 = SHA256.Create();
-        var hashData = sha256.ComputeHash(stream.GetBuffer(), 0, (int)stream.Length);
+        using var hashAlgorithm = SHA384.Create();
+        var hashData = hashAlgorithm.ComputeHash(stream.GetBuffer(), 0, (int)stream.Length);
 
         return ConvertToHexString(hashData);
 
@@ -185,7 +185,7 @@ private sealed class IncrementalHashStream : Stream
         public static IncrementalHashStream? ThreadStaticInstance;
 
         /// <summary>The <see cref="IncrementalHash"/> used by this instance.</summary>
-        private readonly IncrementalHash _hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);
+        private readonly IncrementalHash _hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA384);
 
         /// <summary>Gets the current hash and resets.</summary>
         public void GetHashAndReset(Span<byte> bytes) => _hash.GetHashAndReset(bytes);

src/Libraries/Microsoft.Extensions.AI.Evaluation.Reporting/CSharp/ResponseCachingChatClient.cs

@@ -125,6 +125,6 @@ protected override async Task WriteCacheStreamingAsync(
         }
     }
 
-    protected override string GetCacheKey(params ReadOnlySpan<object?> values)
-        => base.GetCacheKey([.. values, .. _cachingKeys]);
+    protected override string GetCacheKey(IEnumerable<ChatMessage> messages, ChatOptions? options, params ReadOnlySpan<object?> additionalValues)
+        => base.GetCacheKey(messages, options, [.. additionalValues, .. _cachingKeys]);
 }

src/Libraries/Microsoft.Extensions.AI/ChatCompletion/CachingChatClient.cs

@@ -53,7 +53,7 @@ public override async Task<ChatResponse> GetResponseAsync(
         // We're only storing the final result, not the in-flight task, so that we can avoid caching failures
         // or having problems when one of the callers cancels but others don't. This has the drawback that
         // concurrent callers might trigger duplicate requests, but that's acceptable.
-        var cacheKey = GetCacheKey(_boxedFalse, messages, options);
+        var cacheKey = GetCacheKey(messages, options, _boxedFalse);
 
         if (await ReadCacheAsync(cacheKey, cancellationToken).ConfigureAwait(false) is not { } result)
         {
@@ -76,7 +76,7 @@ public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseA
             // we make a streaming request, yielding those results, but then convert those into a non-streaming
             // result and cache it. When we get a cache hit, we yield the non-streaming result as a streaming one.
 
-            var cacheKey = GetCacheKey(_boxedTrue, messages, options);
+            var cacheKey = GetCacheKey(messages, options, _boxedTrue);
             if (await ReadCacheAsync(cacheKey, cancellationToken).ConfigureAwait(false) is { } chatResponse)
             {
                 // Yield all of the cached items.
@@ -101,7 +101,7 @@ public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseA
         }
         else
         {
-            var cacheKey = GetCacheKey(_boxedTrue, messages, options);
+            var cacheKey = GetCacheKey(messages, options, _boxedTrue);
             if (await ReadCacheStreamingAsync(cacheKey, cancellationToken).ConfigureAwait(false) is { } existingChunks)
             {
                 // Yield all of the cached items.
@@ -129,9 +129,11 @@ public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseA
     }
 
     /// <summary>Computes a cache key for the specified values.</summary>
-    /// <param name="values">The values to inform the key.</param>
+    /// <param name="messages">The messages to inform the key.</param>
+    /// <param name="options">The <see cref="ChatOptions"/> to inform the key.</param>
+    /// <param name="additionalValues">Any other values to inform the key.</param>
     /// <returns>The computed key.</returns>
-    protected abstract string GetCacheKey(params ReadOnlySpan<object?> values);
+    protected abstract string GetCacheKey(IEnumerable<ChatMessage> messages, ChatOptions? options, params ReadOnlySpan<object?> additionalValues);
 
     /// <summary>
     /// Returns a previously cached <see cref="ChatResponse"/>, if available.

src/Libraries/Microsoft.Extensions.AI/ChatCompletion/DistributedCachingChatClient.cs

@@ -97,21 +97,24 @@ protected override async Task WriteCacheStreamingAsync(string key, IReadOnlyList
     }
 
     /// <summary>Computes a cache key for the specified values.</summary>
-    /// <param name="values">The values to inform the key.</param>
+    /// <param name="messages">The messages to inform the key.</param>
+    /// <param name="options">The <see cref="ChatOptions"/> to inform the key.</param>
+    /// <param name="additionalValues">Any other values to inform the key.</param>
     /// <returns>The computed key.</returns>
     /// <remarks>
     /// <para>
-    /// The <paramref name="values"/> are serialized to JSON using <see cref="JsonSerializerOptions"/> in order to compute the key.
+    /// The <paramref name="messages"/>, <paramref name="options"/>, and <paramref name="additionalValues"/> are serialized to JSON using <see cref="JsonSerializerOptions"/>
+    /// in order to compute the key.
     /// </para>
     /// <para>
     /// The generated cache key is not guaranteed to be stable across releases of the library.
     /// </para>
     /// </remarks>
-    protected override string GetCacheKey(params ReadOnlySpan<object?> values)
+    protected override string GetCacheKey(IEnumerable<ChatMessage> messages, ChatOptions? options, params ReadOnlySpan<object?> additionalValues)
     {
         // Bump the cache version to invalidate existing caches if the serialization format changes in a breaking way.
         const int CacheVersion = 1;
 
-        return AIJsonUtilities.HashDataToString([CacheVersion, .. values], _jsonSerializerOptions);
+        return AIJsonUtilities.HashDataToString([CacheVersion, messages, options, .. additionalValues], _jsonSerializerOptions);
     }
 }

test/Libraries/Microsoft.Extensions.AI.Tests/ChatCompletion/DistributedCachingChatClientTest.cs

@@ -801,18 +801,10 @@ private static async Task AssertResponsesEqualAsync(IReadOnlyList<ChatResponseUp
     private sealed class CachingChatClientWithCustomKey(IChatClient innerClient, IDistributedCache storage)
         : DistributedCachingChatClient(innerClient, storage)
     {
-        protected override string GetCacheKey(params ReadOnlySpan<object?> values)
+        protected override string GetCacheKey(IEnumerable<ChatMessage> messages, ChatOptions? options, params ReadOnlySpan<object?> additionalValues)
         {
-            var baseKey = base.GetCacheKey(values);
-            foreach (var value in values)
-            {
-                if (value is ChatOptions options)
-                {
-                    return baseKey + options.AdditionalProperties?["someKey"]?.ToString();
-                }
-            }
-
-            return baseKey;
+            var baseKey = base.GetCacheKey(messages, options, additionalValues);
+            return baseKey + options?.AdditionalProperties?["someKey"]?.ToString();
         }
     }