Imaging Configuration: Auto-generate HMAC secret key for new installs

[AndyButland]

Description

As a security hardening exercise, this PR will ensure that an HMAC key for image processing is generated by default for new installs.

The Umbraco:CMS:Imaging:HMACSecretKey setting provides DDoS protection for image processing by signing image URLs with HMAC-SHA256. Currently it defaults to an empty byte array (disabled). This change ensures new installs get a unique key generated automatically so HMAC protection is enabled out of the box. Existing installs (upgrades) are not affected.

Testing

Automated

Unit tests for HmacSecretKeyService have been added.

Manual

Attended Install Verification

Create a new install based on the code in this PR. The approach I've taken was to:

• Download the .nupkg files from the pipeline run for this PR into a local folder where they can be used as a NuGet feed (in my case c:\repos\nuget).
• Create a new Umbraco project with:

dotnet new uninstall Umbraco.Templates
dotnet new install "c:\repos\nuget\Umbraco.Templates.17.3.0--rc.preview.117.gc3cd5f5.nupkg"
dotnet new umbraco --name TestHmac
cd .\TestHmac
code .

Add the following NuGet.config to the root of the project:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="Local Feed" value="c:\repos\nuget" />
  </packageSources>

  <activePackageSource>
    <add key="All" value="(Aggregate source)" />
  </activePackageSource>

</configuration>

dotnet run

Complete the installer.

Verify that HMACSecretKey is written to appsettings.json

Unattended Install Verification (Without Existing Key)

Delete the project folder from the previous test.

dotnet new umbraco --name TestHmac
cd .\TestHmac
code .

Restore/recreate the NuGet.config file.

Add the following settings in appSettings.json, under Umbraco:CMS:

  "Unattended": {
    "InstallUnattended": true,
    "UnattendedUserName": "Test User",
    "UnattendedUserEmail": "test@test.com",
    "UnattendedUserPassword": "testtesttest",
    "UnattendedTelemetryLevel": "Detailed"
  },

Add the connection string:

  "ConnectionStrings": {
    "umbracoDbDSN": "Data Source=|DataDirectory|/Umbraco.sqlite.db;Cache=Shared;Foreign Keys=True;Pooling=True",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.Sqlite"
  }

dotnet run

Verify that the unattended install completes and HMACSecretKey is written to appsettings.json

Unattended Install Verification (With Existing Key)

Repeat the above but with an existing value in HMACSecretKey, e.g.:

  "Imaging": {
    "HMACSecretKey": "Qa\u002Bm3Fb9u5o8uP\u002B3HiJOLB092rZkA59vxgx08h/onI7YG/4OJGWZhBG\u002BTsSaZtZFymG4GF1C0VCNXBdGy9hXYA=="
  }

Verify that the unattended install completes and HMACSecretKey is unchanged.

[Copilot]

Pull request overview

Enables imaging URL HMAC protection by auto-generating and persisting a per-install secret key during new installs (interactive + unattended), without affecting upgrades.

Changes:

• Introduces IHmacSecretKeyService / HmacSecretKeyService to generate and persist a 64-byte HMAC key to configuration.
• Adds an install-only step (HmacSecretKeyStep) and wires it into the interactive installer pipeline.
• Extends unattended install handling to generate the key and adds config-manipulator support for writing Umbraco:CMS:Imaging:HMACSecretKey.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Umbraco.Tests.UnitTests/Umbraco.Core/Security/HmacSecretKeyServiceTests.cs	Adds unit coverage for key presence detection and persistence behavior.
src/Umbraco.Infrastructure/Configuration/JsonConfigManipulator.cs	Implements config write support for the imaging HMAC secret key path.
src/Umbraco.Core/Security/IHmacSecretKeyService.cs	Defines the service contract for checking/creating the imaging HMAC key.
src/Umbraco.Core/Security/HmacSecretKeyService.cs	Implements key generation + persistence via IConfigManipulator.
src/Umbraco.Core/Installer/Steps/HmacSecretKeyStep.cs	Adds an install step to create the key during interactive installs.
src/Umbraco.Core/DependencyInjection/UmbracoBuilder.cs	Registers the new HMAC secret key service in DI.
src/Umbraco.Core/Configuration/IConfigManipulator.cs	Adds SetImagingHmacSecretKeyAsync (with default interface implementation for compatibility).
src/Umbraco.Cms.Api.Management/Install/PostUnattendedInstallNotificationHandler.cs	Generates the key after unattended installs (plus backward-compatible ctor).
src/Umbraco.Cms.Api.Management/DependencyInjection/InstallerBuilderExtensions.cs	Wires HmacSecretKeyStep into the new-install step pipeline.

[nikolajlauridsen]

Looks great, only one suggestion about the signature of the TryCreateHmacSecretKeyAsync method.

Off to do some testing

[nikolajlauridsen]

Tests out good, only have the one comment, but will approve since it's a minor thing

[iOvergaard]

Just commenting to state the obvious, but this change will prevent anyone from accessing cropped images manually. So there is probably documentation throughout the Umbraco-verse stating that you can do image.jpg?width=500&mode=crop, but with this change on new installs, that is not possible anymore unless you know the HMAC code and have generated the necessary SHA, that is.
This should already be covered throughout all Umbraco property editors, but worth looking into where this should be mentioned in the Backoffice/Extensions UmbracoDocs, too, and if it possibly could be marked as "breaking" (argumentable since it only applies to new installs).

[AndyButland]

Docs PR is here: umbraco/UmbracoDocs#7864