From 5ffa8ae57d6d364a7325e4f2cb0b11a7dce86def Mon Sep 17 00:00:00 2001 From: David Boike Date: Mon, 22 Jun 2026 11:53:21 -0500 Subject: [PATCH] Change to hostid hash generation docs --- ...s_host-id-generation_core_[10,).partial.md | 40 ------------------- ...host-id-generation_core_[10,11).partial.md | 28 +++++++++++++ nservicebus/upgrades/10to11/index.md | 16 ++++++-- 3 files changed, 41 insertions(+), 43 deletions(-) delete mode 100644 nservicebus/compliance/fips_host-id-generation_core_[10,).partial.md create mode 100644 nservicebus/compliance/fips_host-id-generation_core_[10,11).partial.md diff --git a/nservicebus/compliance/fips_host-id-generation_core_[10,).partial.md b/nservicebus/compliance/fips_host-id-generation_core_[10,).partial.md deleted file mode 100644 index a2d3bc71522..00000000000 --- a/nservicebus/compliance/fips_host-id-generation_core_[10,).partial.md +++ /dev/null @@ -1,40 +0,0 @@ -## NServiceBus - -Starting in version 10.2, NServiceBus uses a non-cryptographic hash algorithm (XxHash128) to generate deterministic unique identifiers for endpoints, also known as host identifiers (HostIds). Because XxHash128 is not a cryptographic algorithm, FIPS policy enforcement does not block host identifier generation; the host ID workaround described below is no longer needed. - -### Migrating from MD5 to XxHash128 host identifiers - -The XxHash128-based algorithm produces different host identifiers than the legacy MD5-based algorithm. In version 10.2, the legacy MD5 algorithm remains the default, in order to avoid duplicate endpoint entries in [the ServicePulse Heartbeats view](/monitoring/heartbeats/in-servicepulse.md) after upgrading. - -To opt into the new XxHash128-based host identifier, set the following AppContext switch before endpoint startup: - -```csharp -AppContext.SetSwitch("NServiceBus.Core.Hosting.UseV2DeterministicGuid", true); -``` - -Or via environment variable (.NET 9+): - -```text -DOTNET_NServiceBus_Core_Hosting_UseV2DeterministicGuid=true -``` - -Or via MSBuild in the project file: - -```xml - - - -``` - -> [!WARNING] -> Changing the host identifier algorithm changes the host ID that identifies an endpoint in ServicePulse and ServiceControl. Only enable this switch after coordinating with operations teams to ensure monitoring continuity. Endpoints that change their host identifier will appear as new entries in ServicePulse until stale instances are [removed from the monitoring view](/monitoring/metrics/in-servicepulse.md#disconnected-endpoints-removing-disconnected-endpoints). - -In version 11, the XxHash128 algorithm will become the default, and the legacy MD5 algorithm will require explicit opt-out. In version 12, the legacy MD5 algorithm will be removed entirely. - -### Manual host identifier override (legacy approach) - -Before version 10.2, the only workaround for FIPS-enabled systems was to override the host identifier using a non-cryptographic hash that is not subject to FIPS enforcement, such as XxHash128 from the `System.IO.Hashing` package, which targets .NET Standard 2.0 and .NET Framework 4.6.2. This is no longer needed now that NServiceBus uses XxHash128 internally. - -snippet: XxHash128DeterministicGuid - -snippet: HostIdFixer \ No newline at end of file diff --git a/nservicebus/compliance/fips_host-id-generation_core_[10,11).partial.md b/nservicebus/compliance/fips_host-id-generation_core_[10,11).partial.md new file mode 100644 index 00000000000..5c02bc12410 --- /dev/null +++ b/nservicebus/compliance/fips_host-id-generation_core_[10,11).partial.md @@ -0,0 +1,28 @@ +## NServiceBus + +Starting in version 10.2, NServiceBus can use a non-cryptographic hash algorithm (XxHash128) to generate deterministic unique identifiers for endpoints, also known as host identifiers (HostIds). Because XxHash128 is not a cryptographic algorithm, FIPS policy enforcement does not block host identifier generation; the host ID workaround described below is no longer needed. + +To ensure the non-cryptographic hash is used in NServiceBus 10, set the following AppContext switch before endpoint startup: + +```csharp +AppContext.SetSwitch("NServiceBus.Core.Hosting.UseV2DeterministicGuid", true); +``` + +Or via environment variable: + +```text +DOTNET_NServiceBus_Core_Hosting_UseV2DeterministicGuid=true +``` + +Or via MSBuild in a project file: + +```xml + + + +``` + +> [!WARNING] +> Changing the host identifier algorithm changes the host ID that identifies an endpoint in ServicePulse and ServiceControl. Changes to the algorithm will cause existing known endpoints to appear inactive in the ServicePulse [heartbeats](/monitoring/heartbeats/in-servicepulse.md) and [monitoring](/monitoring/metrics/in-servicepulse.md) views while new instances (with the changed host identifiers) appear in their place. Stale instances should be [removed from the monitoring view](/monitoring/metrics/in-servicepulse.md#disconnected-endpoints-removing-disconnected-endpoints). +> +> See the [NServiceBus version 10 to 11 upgrade guide](/nservicebus/upgrades/10to11/#host-identifier-algorithm-change) for more information on migrating from MD5 to the XxHash128 hash algorithm. \ No newline at end of file diff --git a/nservicebus/upgrades/10to11/index.md b/nservicebus/upgrades/10to11/index.md index b96e4a5ff53..33b7262d4ce 100644 --- a/nservicebus/upgrades/10to11/index.md +++ b/nservicebus/upgrades/10to11/index.md @@ -196,13 +196,23 @@ The following APIs are deprecated: ## Host identifier algorithm change -In version 11, the default algorithm for generating deterministic host identifiers changes from MD5 to XxHash128 (RFC 9562 version 8 GUIDs). This produces different host identifiers, which affects how endpoints are identified in [ServicePulse](/servicepulse/) and [ServiceControl](/servicecontrol/). +In version 11, the default algorithm for generating deterministic host identifiers changes from MD5 to XxHash128 (RFC 9562 version 8 GUIDs). This produces different host identifiers, which affects how endpoints are identified in [ServicePulse](/servicepulse/) and [ServiceControl](/servicecontrol/). Changing the algorithm will cause existing known endpoints to appear inactive in the ServicePulse [heartbeats](/monitoring/heartbeats/in-servicepulse.md) and [monitoring](/monitoring/metrics/in-servicepulse.md) views, while new instances (with the changed host identifiers) appear in their place. ### Rationale This change provides a path for customers who require **FIPS-compliant** host identifiers (see [FIPS compliance](/nservicebus/compliance/fips.md)). The legacy MD5-based algorithm is not FIPS-compliant; by moving to the new `XxHash128` algorithm, the framework uses a compliant standard by default. -To ensure a predictable transition, this is designed as a multi-phase migration. In version 11, the new algorithm becomes the default. By making this an explicit switch rather than an automatic change, there is a clear "escape hatch" to preserve legacy host IDs if correlation with older monitoring data (such as ServicePulse) must be maintained during the transition. +To ensure a predictable transition, this is designed as a multi-phase migration: + +| NServiceBus Versions | Hashes Available | Default Hash | App Switch | +|:-:|:-:|:-:|:-:| +| <= 10.2 | MD5 Only | MD5 | - | +| >= 10.2 && < 11.0 | MD5 + XxHash128 | MD5 | Can opt in | +| >= 11.0 && < 12.0 | MD5 + XxHash128 | XxHash128 | Can opt out | +| >= 12.0 | XxHash128 Only | XxHash128 | - | + + +In version 11, XxHash128 becomes the default. By making this an explicit switch rather than an automatic change, there is a clear "escape hatch" to preserve legacy host IDs if correlation with older monitoring data (such as ServicePulse) must be maintained during the transition. This approach allows the framework to move toward a compliant default while providing the necessary flexibility to manage existing integrations before the legacy algorithm is removed in version 12. @@ -218,7 +228,7 @@ To preserve the existing MD5-based host identifier after upgrading, set the foll AppContext.SetSwitch("NServiceBus.Core.Hosting.UseV2DeterministicGuid", false); ``` -Or via environment variable (.NET 9+): +Or via environment variable: ```text DOTNET_NServiceBus_Core_Hosting_UseV2DeterministicGuid=false