From 744dd103a50e8ae8075efac35091e14a92d93d82 Mon Sep 17 00:00:00 2001 From: James Jackson-South Date: Sun, 24 Apr 2022 01:34:38 +1000 Subject: [PATCH] Update to latest refs and add Web docs --- articles/imagesharp.web/gettingstarted.md | 55 ++++++++++++++++++- articles/imagesharp.web/imagecaches.md | 1 - articles/imagesharp.web/processingcommands.md | 31 +++++++++++ ext/ImageSharp | 2 +- ext/ImageSharp.Web | 2 +- 5 files changed, 87 insertions(+), 4 deletions(-) diff --git a/articles/imagesharp.web/gettingstarted.md b/articles/imagesharp.web/gettingstarted.md index 975f6b418..472e8542f 100644 --- a/articles/imagesharp.web/gettingstarted.md +++ b/articles/imagesharp.web/gettingstarted.md @@ -63,5 +63,58 @@ services.AddImageSharp() options.CacheFolder = "different-cache"; }); ``` - + +>[!IMPORTANT] +>ImageSharp.Web v2.0.0 contains breaking changes to caching which require additional configuration for v1.x installs. + +With ImageSharp.Web v2.0.0 a new concept @SixLabors.ImageSharp.Web.Caching.ICacheKey was introduced to allow greater flexibility when generating cached file names. To preserve the v1.x cache format users must configure two settings: + +1. @SixLabors.ImageSharp.Web.Caching.ICacheKey should be configured to use @SixLabors.ImageSharp.Web.Caching.LegacyV1CacheKey +2. @SixLabors.ImageSharp.Web.Caching.PhysicalFileSystemCacheOptions.CacheFolderDepth should be configured to use the same value as @SixLabors.ImageSharp.Web.Middleware.ImageSharpMiddlewareOptions.CacheHashLength - Default `12`. + +A complete configuration sample allowing the replication of legacy v1.x behavior can be found below: + +```c# +services.AddImageSharp(options => +{ + // Set to previous default value of CachedNameLength + options.CacheHashLength = 12; + + // Use the same command parsing as v1.x + options.OnParseCommandsAsync = c => + { + if (c.Commands.Count == 0) + { + return Task.CompletedTask; + } + + // It's a good idea to have this to provide very basic security. + // We can safely use the static resize processor properties. + uint width = c.Parser.ParseValue( + c.Commands.GetValueOrDefault(ResizeWebProcessor.Width), + c.Culture); + + uint height = c.Parser.ParseValue( + c.Commands.GetValueOrDefault(ResizeWebProcessor.Height), + c.Culture); + + if (width > 4000 && height > 4000) + { + c.Commands.Remove(ResizeWebProcessor.Width); + c.Commands.Remove(ResizeWebProcessor.Height); + } + + return Task.CompletedTask; + }); +}) +.Configure(options => +{ + // Ensure this value is the same as CacheHashLength to generate a backwards-compatible cache folder structure + options.CacheFolderDepth = 12; +}) +.SetCacheKey() +.ClearProviders() +.AddProvider(); +``` + Full Configuration API options are available [here](xref:SixLabors.ImageSharp.Web.DependencyInjection.ImageSharpBuilderExtensions). \ No newline at end of file diff --git a/articles/imagesharp.web/imagecaches.md b/articles/imagesharp.web/imagecaches.md index 1defdd84d..1421802c4 100644 --- a/articles/imagesharp.web/imagecaches.md +++ b/articles/imagesharp.web/imagecaches.md @@ -13,7 +13,6 @@ The @"SixLabors.ImageSharp.Web.Caching.PhysicalFileSystemCache", by default, sto Images are cached in separate folders based upon a hash of the request URL. this allows the caching of millions of image files without slowing down the file system. - ### AzureBlobStorageImageCache This cache allows the caching of image files using [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) and is available as an external package installable via [NuGet](https://www.nuget.org/packages/SixLabors.ImageSharp.Web.Providers.Azure) diff --git a/articles/imagesharp.web/processingcommands.md b/articles/imagesharp.web/processingcommands.md index b42670f9f..6ab22dbc0 100644 --- a/articles/imagesharp.web/processingcommands.md +++ b/articles/imagesharp.web/processingcommands.md @@ -90,3 +90,34 @@ Allows the changing of the background color of transparent images. {PATH_TO_YOUR_IMAGE}?bgcolor=128,64,32 {PATH_TO_YOUR_IMAGE}?bgcolor=128,64,32,16 ``` + +## Securing Processing Commands + +With ImageSharp.Web it is possible to configure an action to generate an HMAC by setting the @SixLabors.ImageSharp.Web.Middleware.ImageSharpMiddlewareOptions.HMACSecretKey property to any byte array value. This triggers checks in the middleware to look for and compare a HMAC hash of the request URL with the hash that is passed alongside the commands. + +In cryptography, an HMAC (sometimes expanded as either keyed-hash message authentication code or hash-based message authentication code) is a specific type of message authentication code (MAC) involving a cryptographic hash function and a secret cryptographic key. As with any MAC, it may be used to simultaneously verify both the data integrity and authenticity of a message. + +HMAC can provide authentication using a shared secret instead of using digital signatures with asymmetric cryptography. It trades off the need for a complex public key infrastructure by delegating the key exchange to the communicating parties, who are responsible for establishing and using a trusted channel to agree on the key prior to communication. + +Any cryptographic hash function, such as SHA-2 or SHA-3, may be used in the calculation of an HMAC; the resulting MAC algorithm is termed HMAC-X, where X is the hash function used (e.g. HMAC-SHA256 or HMAC-SHA3-512). The cryptographic strength of the HMAC depends upon the cryptographic strength of the underlying hash function, the size of its hash output, and the size and quality of the key. + +HMAC does not encrypt the message. Instead, the message (encrypted or not) must be sent alongside the HMAC hash. Parties with the secret key will hash the message again themselves, and if it is authentic, the received and computed hashes will match. + +By default ImageSharp.Web will use a HMAC-SHA256 algorithm. + +```c# +private Func> onComputeHMACAsync = (context, secret) => +{ + string uri = CaseHandlingUriBuilder.BuildRelative( + CaseHandlingUriBuilder.CaseHandling.LowerInvariant, + context.Context.Request.PathBase, + context.Context.Request.Path, + QueryString.Create(context.Commands)); + + return Task.FromResult(HMACUtilities.ComputeHMACSHA256(uri, secret)); +}; +``` + +Users can replicate that key using the same @SixLabors.ImageSharp.Web.CaseHandlingUriBuilder and @SixLabors.ImageSharp.Web.HMACUtilities APIs to generate the HMAC hash on the client. The hash must be passed via a command using the @SixLabors.ImageSharp.Web.HMACUtilities.TokenCommand constant. + +Any invalid matches are rejected at the very start of the processing pipeline with a 400 HttpResponse code. \ No newline at end of file diff --git a/ext/ImageSharp b/ext/ImageSharp index 136cc143b..3139a8a00 160000 --- a/ext/ImageSharp +++ b/ext/ImageSharp @@ -1 +1 @@ -Subproject commit 136cc143bba2fca255328751dd4580e4f8d413c3 +Subproject commit 3139a8a00d82620767017c1951703954beb2b2b3 diff --git a/ext/ImageSharp.Web b/ext/ImageSharp.Web index 40a50756b..ba216daac 160000 --- a/ext/ImageSharp.Web +++ b/ext/ImageSharp.Web @@ -1 +1 @@ -Subproject commit 40a50756bca09c43814519e13543bc027c8fb793 +Subproject commit ba216daac84b5fc12b160b1a1c4c4f835ba1059b