Merge pull request #250 from SixLabors/js/hmac

Add HMAC authentication options.

Author: JimBobSquarePants

src/ImageSharp.Web/Caching/SHA256CacheHash.cs

@@ -33,18 +33,16 @@ public SHA256CacheHash(IOptions<ImageSharpMiddlewareOptions> options)
         public string Create(string value, uint length)
         {
             int byteCount = Encoding.ASCII.GetByteCount(value);
-
-            // Allocating a buffer from the pool is ~27% slower than stackalloc so use that for short strings
-            if (byteCount < 257)
-            {
-                return HashValue(value, length, stackalloc byte[byteCount]);
-            }
-
             byte[] buffer = null;
+
             try
             {
-                buffer = ArrayPool<byte>.Shared.Rent(byteCount);
-                return HashValue(value, length, buffer.AsSpan(0, byteCount));
+                // Allocating a buffer from the pool is ~27% slower than stackalloc so use that for short strings
+                Span<byte> bytes = byteCount <= 128
+                    ? stackalloc byte[byteCount]
+                    : (buffer = ArrayPool<byte>.Shared.Rent(byteCount)).AsSpan(0, byteCount);
+
+                return HashValue(value, length, bytes);
             }
             finally
             {

src/ImageSharp.Web/Caching/UriAbsoluteCacheKey.cs

@@ -13,6 +13,6 @@ public class UriAbsoluteCacheKey : ICacheKey
     {
         /// <inheritdoc/>
         public string Create(HttpContext context, CommandCollection commands)
-            => CacheKeyHelper.BuildAbsoluteKey(CacheKeyHelper.CaseHandling.None, context.Request.Host, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
+            => CaseHandlingUriBuilder.BuildAbsolute(CaseHandlingUriBuilder.CaseHandling.None, context.Request.Host, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
     }
 }

src/ImageSharp.Web/Caching/UriAbsoluteLowerInvariantCacheKey.cs

@@ -13,6 +13,6 @@ public class UriAbsoluteLowerInvariantCacheKey : ICacheKey
     {
         /// <inheritdoc/>
         public string Create(HttpContext context, CommandCollection commands)
-            => CacheKeyHelper.BuildAbsoluteKey(CacheKeyHelper.CaseHandling.LowerInvariant, context.Request.Host, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
+            => CaseHandlingUriBuilder.BuildAbsolute(CaseHandlingUriBuilder.CaseHandling.LowerInvariant, context.Request.Host, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
     }
 }

src/ImageSharp.Web/Caching/UriRelativeCacheKey.cs

@@ -13,6 +13,6 @@ public class UriRelativeCacheKey : ICacheKey
     {
         /// <inheritdoc/>
         public string Create(HttpContext context, CommandCollection commands)
-            => CacheKeyHelper.BuildRelativeKey(CacheKeyHelper.CaseHandling.None, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
+            => CaseHandlingUriBuilder.BuildRelative(CaseHandlingUriBuilder.CaseHandling.None, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
     }
 }

src/ImageSharp.Web/Caching/UriRelativeLowerInvariantCacheKey.cs

@@ -13,6 +13,6 @@ public class UriRelativeLowerInvariantCacheKey : ICacheKey
     {
         /// <inheritdoc/>
         public string Create(HttpContext context, CommandCollection commands)
-            => CacheKeyHelper.BuildRelativeKey(CacheKeyHelper.CaseHandling.LowerInvariant, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
+            => CaseHandlingUriBuilder.BuildRelative(CaseHandlingUriBuilder.CaseHandling.LowerInvariant, context.Request.PathBase, context.Request.Path, QueryString.Create(commands));
     }
 }

…ImageSharp.Web/Caching/CacheKeyHelper.cs …ImageSharp.Web/CaseHandlingUriBuilder.cssrc/ImageSharp.Web/Caching/CacheKeyHelper.cs renamed to src/ImageSharp.Web/CaseHandlingUriBuilder.cs src/ImageSharp.Web/Caching/CacheKeyHelper.cs renamed to src/ImageSharp.Web/CaseHandlingUriBuilder.cs

@@ -6,18 +6,29 @@
 using System.Runtime.CompilerServices;
 using Microsoft.AspNetCore.Http;
 
-namespace SixLabors.ImageSharp.Web.Caching
+namespace SixLabors.ImageSharp.Web
 {
     /// <summary>
-    /// Optimized helper methods for generating cache keys from URI components. Much of this code has been adapted from the MIT licensed .NET runtime.
+    /// Optimized helper methods for generating encoded Uris from URI components.
+    /// Much of this code has been adapted from the MIT licensed .NET runtime.
     /// </summary>
-    internal static class CacheKeyHelper
+    public static class CaseHandlingUriBuilder
     {
         private static readonly SpanAction<char, (bool LowerInvariant, string Host, string PathBase, string Path, string Query)> InitializeAbsoluteUriStringSpanAction = new(InitializeAbsoluteUriString);
 
+        /// <summary>
+        /// Provides Uri case handling options.
+        /// </summary>
         public enum CaseHandling
         {
+            /// <summary>
+            /// No adjustments to casing are made.
+            /// </summary>
             None,
+
+            /// <summary>
+            /// All URI components are converted to lower case using the invariant culture before combining.
+            /// </summary>
             LowerInvariant
         }
 
@@ -29,14 +40,14 @@ public enum CaseHandling
         /// <param name="path">The portion of the request path that identifies the requested resource.</param>
         /// <param name="query">The query, if any.</param>
         /// <returns>The combined URI components, properly encoded for use in HTTP headers.</returns>
-        public static string BuildRelativeKey(
+        public static string BuildRelative(
             CaseHandling handling,
             PathString pathBase = default,
             PathString path = default,
             QueryString query = default)
 
             // Take any potential performance hit vs concatination for code reading sanity.
-            => BuildAbsoluteKey(handling, default, pathBase, path, query);
+            => BuildAbsolute(handling, default, pathBase, path, query);
 
         /// <summary>
         /// Combines the given URI components into a string that is properly encoded for use in HTTP headers.
@@ -48,7 +59,7 @@ public static string BuildRelativeKey(
         /// <param name="path">The portion of the request path that identifies the requested resource.</param>
         /// <param name="query">The query, if any.</param>
         /// <returns>The combined URI components, properly encoded for use in HTTP headers.</returns>
-        public static string BuildAbsoluteKey(
+        public static string BuildAbsolute(
             CaseHandling handling,
             HostString host,
             PathString pathBase = default,
@@ -113,7 +124,7 @@ private static int CopyTextToBufferLowerInvariant(Span<char> buffer, int index,
             => index + text.ToLowerInvariant(buffer.Slice(index, text.Length));
 
         /// <summary>
-        /// Initializes the URI <see cref="string"/> for <see cref="BuildAbsoluteKey(CaseHandling, HostString, PathString, PathString, QueryString)"/>.
+        /// Initializes the URI <see cref="string"/> for <see cref="BuildAbsolute(CaseHandling, HostString, PathString, PathString, QueryString)"/>.
         /// </summary>
         /// <param name="buffer">The URI <see cref="string"/>'s <see cref="char"/> buffer.</param>
         /// <param name="uriParts">The URI parts.</param>

src/ImageSharp.Web/Commands/Converters/SimpleCommandConverter{T}.cs

@@ -11,7 +11,7 @@ namespace SixLabors.ImageSharp.Web.Commands.Converters
     /// The generic converter for simple types that implement <see cref="IConvertible"/>.
     /// </summary>
     /// <typeparam name="T">The type of object to convert to.</typeparam>
-    internal sealed class SimpleCommandConverter<T> : ICommandConverter<T>
+    public sealed class SimpleCommandConverter<T> : ICommandConverter<T>
         where T : IConvertible
     {
         /// <inheritdoc/>

src/ImageSharp.Web/HMACUtilities.cs

@@ -0,0 +1,100 @@
+// Copyright (c) Six Labors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+using System.Buffers;
+using System.Runtime.CompilerServices;
+using System.Security.Cryptography;
+using System.Text;
+using SixLabors.ImageSharp.Web.Caching;
+
+namespace SixLabors.ImageSharp.Web
+{
+    /// <summary>
+    /// Provides methods to compute a Hash-based Message Authentication Code (HMAC).
+    /// </summary>
+    public static class HMACUtilities
+    {
+        /// <summary>
+        /// The command used by image requests for transporting Hash-based Message Authentication Code (HMAC) tokens.
+        /// </summary>
+        public const string TokenCommand = "hmac";
+
+        /// <summary>
+        /// Computes a Hash-based Message Authentication Code (HMAC) by using the SHA256 hash function.
+        /// </summary>
+        /// <param name="value">The value to hash</param>
+        /// <param name="secret">
+        /// The secret key for <see cref="HMACSHA256"/> encryption.
+        /// The key can be any length. However, the recommended size is 64 bytes.
+        /// </param>
+        /// <returns>The hashed <see cref="string"/>.</returns>
+        public static unsafe string ComputeHMACSHA256(string value, byte[] secret)
+        {
+            // TODO: In .NET 6 we can use single instance versions
+            using var hmac = new HMACSHA256(secret);
+            return CreateHMAC(value, hmac);
+        }
+
+        /// <summary>
+        /// Computes a Hash-based Message Authentication Code (HMAC) by using the SHA384 hash function.
+        /// </summary>
+        /// <param name="value">The value to hash</param>
+        /// <param name="secret">
+        /// The secret key for <see cref="HMACSHA256"/> encryption.
+        /// The key can be any length. However, the recommended size is 128 bytes.
+        /// </param>
+        /// <returns>The hashed <see cref="string"/>.</returns>
+        public static unsafe string ComputeHMACSHA384(string value, byte[] secret)
+        {
+            using var hmac = new HMACSHA384(secret);
+            return CreateHMAC(value, hmac);
+        }
+
+        /// <summary>
+        /// Computes a Hash-based Message Authentication Code (HMAC) by using the SHA512 hash function.
+        /// </summary>
+        /// <param name="value">The value to hash</param>
+        /// <param name="secret">
+        /// The secret key for <see cref="HMACSHA256"/> encryption.
+        /// The key can be any length. However, the recommended size is 128 bytes.
+        /// </param>
+        /// <returns>The hashed <see cref="string"/>.</returns>
+        public static unsafe string ComputeHMACSHA512(string value, byte[] secret)
+        {
+            using var hmac = new HMACSHA512(secret);
+            return CreateHMAC(value, hmac);
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private static unsafe string CreateHMAC(string value, HMAC hmac)
+        {
+            int byteCount = Encoding.ASCII.GetByteCount(value);
+            byte[] buffer = null;
+
+            try
+            {
+                // Allocating a buffer from the pool is ~27% slower than stackalloc so use that for short strings
+                Span<byte> bytes = byteCount <= 128
+                    ? stackalloc byte[byteCount]
+                    : (buffer = ArrayPool<byte>.Shared.Rent(byteCount)).AsSpan(0, byteCount);
+
+                Encoding.ASCII.GetBytes(value, bytes);
+
+                // Safe to always stackalloc here. We max out at 64 bytes.
+                Span<byte> hash = stackalloc byte[hmac.HashSize / 8];
+                hmac.TryComputeHash(bytes, hash, out int _);
+
+                // Finally encode the hash to make it web safe.
+                return HexEncoder.Encode(hash);
+            }
+            finally
+            {
+                if (buffer is not null)
+                {
+                    ArrayPool<byte>.Shared.Return(buffer);
+                }
+            }
+        }
+    }
+}

src/ImageSharp.Web/Middleware/ImageSharpMiddleware.cs

@@ -41,6 +41,12 @@ private static readonly ConcurrentTLruCache<string, ImageMetadata> SourceMetadat
         private static readonly ConcurrentTLruCache<string, (IImageCacheResolver, ImageCacheMetadata)> CacheResolverLru
             = new(1024, TimeSpan.FromSeconds(30));
 
+        /// <summary>
+        /// Used to temporarily store cached HMAC-s to reduce the overhead of HMAC token generation.
+        /// </summary>
+        private static readonly ConcurrentTLruCache<string, string> HMACTokenLru
+            = new(1024, TimeSpan.FromSeconds(30));
+
         /// <summary>
         /// The function processing the Http request.
         /// </summary>
@@ -191,9 +197,18 @@ public ImageSharpMiddleware(
 
         private async Task Invoke(HttpContext httpContext, bool retry)
         {
-            // We expect to get concrete collection type which removes virtual dispatch concerns and enumerator allocations
             CommandCollection commands = this.requestParser.ParseRequestCommands(httpContext);
 
+            // First check for a HMAC token and capture before the command is stripped out.
+            byte[] secret = this.options.HMACSecretKey;
+            bool checkHMAC = false;
+            string token = null;
+            if (secret?.Length > 0)
+            {
+                checkHMAC = true;
+                token = commands.GetValueOrDefault(HMACUtilities.TokenCommand);
+            }
+
             if (commands.Count > 0)
             {
                 // Strip out any unknown commands, if needed.
@@ -203,18 +218,15 @@ private async Task Invoke(HttpContext httpContext, bool retry)
                     if (!this.knownCommands.Contains(command))
                     {
                         // Need to actually remove, allocates new list to allow modifications
-                        this.StripUnknownCommands(commands, startAtIndex: index);
+                        this.StripUnknownCommands(commands, index);
                         break;
                     }
 
                     index++;
                 }
             }
 
-            await this.options.OnParseCommandsAsync.Invoke(
-                new ImageCommandContext(httpContext, commands, this.commandParser, this.parserCulture));
-
-            // Get the correct service for the request
+            // Get the correct provider for the request
             IImageProvider provider = null;
             foreach (IImageProvider resolver in this.providers)
             {
@@ -225,14 +237,48 @@ await this.options.OnParseCommandsAsync.Invoke(
                 }
             }
 
-            if ((commands.Count == 0 && provider?.ProcessingBehavior != ProcessingBehavior.All)
-                || provider?.IsValidRequest(httpContext) != true)
+            if (provider?.IsValidRequest(httpContext) != true)
+            {
+                // Nothing to do. call the next delegate/middleware in the pipeline
+                await this.next(httpContext);
+                return;
+            }
+
+            ImageCommandContext imageCommandContext = new(httpContext, commands, this.commandParser, this.parserCulture);
+
+            // At this point we know that this is an image request so should attempt to compute a validating HMAC..
+            string hmac = null;
+            if (checkHMAC && token != null)
+            {
+                // Generate and cache a HMAC to validate against based upon the current valid commands from the request.
+                //
+                // If the command collection differs following the stripping of invalid commands prior to this point then this will mean
+                // the token will not match our validating HMAC, however, this would be indicative of an attack and should be treated as such.
+                //
+                // As a rule all image requests should contain valid commands only.
+                hmac = await HMACTokenLru.GetOrAddAsync(token, _ => this.options.OnComputeHMACAsync(imageCommandContext, secret));
+            }
+
+            await this.options.OnParseCommandsAsync.Invoke(imageCommandContext);
+
+            if (commands.Count == 0 && provider?.ProcessingBehavior != ProcessingBehavior.All)
             {
                 // Nothing to do. call the next delegate/middleware in the pipeline
                 await this.next(httpContext);
                 return;
             }
 
+            // At this point we know that this is an image request designed for processing via this middleware.
+            // Check for a token if required and reject if invalid.
+            if (checkHMAC)
+            {
+                if (token == null || hmac != token)
+                {
+                    SetBadRequest(httpContext);
+                    return;
+                }
+            }
+
             IImageResolver sourceImageResolver = await provider.GetAsync(httpContext);
 
             if (sourceImageResolver is null)
@@ -252,6 +298,14 @@ await this.ProcessRequestAsync(
                 retry);
         }
 
+        private static void SetBadRequest(HttpContext httpContext)
+        {
+            // We return a 400 rather than a 401 as we do not want to prompt follow up requests.
+            // We don't log the error to avoid attempts at log poisoning.
+            httpContext.Response.Clear();
+            httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
+        }
+
         private void StripUnknownCommands(CommandCollection commands, int startAtIndex)
         {
             var keys = new List<string>(commands.Keys);