Class IntegrityServiceCollectionExtensions

Namespace

Microsoft.Extensions.DependencyInjection

Assembly

Stratara.Infrastructure.dll

Service-collection extensions that wire HMAC integrity protection for bus envelopes.

public static class IntegrityServiceCollectionExtensions

Inheritance

object

IntegrityServiceCollectionExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

AddBusEnvelopeIntegrity(IServiceCollection, IConfiguration)

Overload that binds BusEnvelopeIntegrityOptions from configuration section SectionName ("BusEnvelopeIntegrity").

public static IServiceCollection AddBusEnvelopeIntegrity(this IServiceCollection services, IConfiguration configuration)

Parameters

services IServiceCollection

The service collection to mutate.

configuration IConfiguration

The configuration root to bind from.

Returns

IServiceCollection

The same service collection, to enable chaining.

Examples

Binds Mode from the BusEnvelopeIntegrity section and leaves the key to the caller, so a host using this overload still has to assign SharedKey:

// appsettings.json: { "BusEnvelopeIntegrity": { "Mode": "Permissive" } }
services.AddBusEnvelopeIntegrity(configuration);
services.Configure<BusEnvelopeIntegrityOptions>(
    o => o.SharedKey = Convert.FromBase64String(configuration["BusEnvelopeIntegrity:SharedKey"]!));

Exceptions

ArgumentNullException

configuration is null.

AddBusEnvelopeIntegrity(IServiceCollection, Action<BusEnvelopeIntegrityOptions>)

Opt in to HMAC integrity protection on every bus envelope. The framework signs outbound CommandEnvelope and EventBundle instances and verifies inbound envelopes according to Mode.

public static IServiceCollection AddBusEnvelopeIntegrity(this IServiceCollection services, Action<BusEnvelopeIntegrityOptions> configure)

Parameters

services IServiceCollection

The service collection to mutate.

configure Action<BusEnvelopeIntegrityOptions>

Callback that populates BusEnvelopeIntegrityOptions.

Returns

IServiceCollection

The same service collection, to enable chaining.

Examples

The key is a byte[] of at least 32 bytes and must be identical on every host that shares the bus. Read it from a secret store rather than from appsettings.json:

services.AddBusEnvelopeIntegrity(options =>
{
    options.Mode = BusEnvelopeIntegrityMode.Strict;
    options.SharedKey = Convert.FromBase64String(configuration["BusEnvelopeIntegrity:SharedKey"]!);
});

Remarks

When this method is not called, IBusEnvelopeSigner stays unregistered and the framework behaves exactly as it did before: envelopes carry no signature, the dispatcher does not verify, and Mode resolves to Off. The threat model trade-off is documented in SECURITY.md.

Every publisher and consumer that share a bus must agree on SharedKey and the active mode. When rolling out integrity to an existing fleet, deploy in two phases:

1. Publishers + consumers on Permissive — new envelopes carry a signature, unsigned in-flight envelopes are still accepted with a warning log.
2. Once every host is signing, switch both fleets to Strict — unsigned or tampered envelopes are rejected.

Exceptions

ArgumentNullException

configure is null.

AddBusEnvelopeIntegrity(IServiceCollection, string, BusEnvelopeIntegrityMode)

Overload that takes the shared key as a base64 string and the enforcement mode directly — the shape a host reaches for first, and the one the start-up probe points at.

public static IServiceCollection AddBusEnvelopeIntegrity(this IServiceCollection services, string base64SharedKey, BusEnvelopeIntegrityMode mode = BusEnvelopeIntegrityMode.Strict)

Parameters

services IServiceCollection

The service collection to mutate.

base64SharedKey string

The HMAC shared secret, base64-encoded. Decodes to at least 32 bytes and must be identical on every host that shares the bus.

mode BusEnvelopeIntegrityMode

Enforcement mode. Defaults to Strict.

Returns

IServiceCollection

The same service collection, to enable chaining.

Examples

services.AddBusEnvelopeIntegrity(
    builder.Configuration["BUS_ENVELOPE_SIGNING_KEY"]!,
    BusEnvelopeIntegrityMode.Permissive);

Remarks

Where the key comes from matters more than this overload does. Read it from a secret store, a key vault or an environment variable injected at deploy time — not from a checked-in appsettings.json. A signing key in source control signs for anyone who can read the repository, which is the threat this option exists to close.

The two other overloads remain the right choice when the key is already a byte[], or when everything but the key is bound from configuration.

Exceptions

ArgumentNullException

base64SharedKey is null.

ArgumentException

base64SharedKey is not valid base64, or decodes to fewer than 32 bytes. Both are checked here rather than at the first publish, so a mistyped secret fails at registration instead of on a message.