Encryption Providers

Dispatch encryption uses IEncryptionProvider as its core abstraction. Key management providers handle key storage, rotation, and envelope encryption via cloud-native or self-hosted vaults.

Before You Start

• .NET 10.0
• Install the required packages:

  dotnet add package Excalibur.Security

• Access to a key management provider (AWS KMS, Azure Key Vault, or HashiCorp Vault)
• Familiarity with security concepts and Dispatch pipeline

Core Registration

using Microsoft.Extensions.DependencyInjection;

// Register via the Dispatch builder (recommended)
services.AddDispatch(dispatch =>
{
    dispatch.AddHandlersFromAssembly(typeof(Program).Assembly);
    dispatch.UseSecurity(configuration);
});

// Or standalone encryption registration
services.AddEncryption(builder =>
{
    // Configure encryption provider, key policies, etc.
});

// Development-only encryption (insecure, for local dev)
services.AddDevEncryption();

---

AWS KMS

Envelope encryption with AWS Key Management Service.

Installation

dotnet add package Excalibur.Compliance.Aws

Setup

// Basic registration
services.AddAwsKmsKeyManagement(options =>
{
    options.KeyId = "arn:aws:kms:us-east-1:123456789:key/your-key-id";
});

// With custom client factory
services.AddAwsKmsKeyManagement(
    sp => new AmazonKeyManagementServiceClient(RegionEndpoint.USEast1),
    options =>
    {
        options.KeyId = "alias/my-key";
    });

// LocalStack for development
services.AddAwsKmsKeyManagementLocalStack(
    localStackEndpoint: "http://localhost:4566",
    options =>
    {
        options.KeyId = "alias/dev-key";
    });

// Multi-region for high availability
services.AddAwsKmsKeyManagementMultiRegion(
    primaryRegion: RegionEndpoint.USEast1,
    replicaRegions: new[] { RegionEndpoint.USWest2, RegionEndpoint.EUWest1 },
    options =>
    {
        options.KeyId = "mrk-key-id";
    });

---

Azure Key Vault

Envelope encryption with Azure Key Vault.

Installation

dotnet add package Excalibur.Compliance.Azure

Setup

// With options callback
services.AddAzureKeyVaultKeyManagement(options =>
{
    options.VaultUri = "https://my-vault.vault.azure.net/";
    options.KeyName = "dispatch-encryption-key";
});

// With pre-built options
var kvOptions = new AzureKeyVaultOptions
{
    VaultUri = "https://my-vault.vault.azure.net/",
    KeyName = "dispatch-encryption-key"
};
services.AddAzureKeyVaultKeyManagement(kvOptions);

// From configuration section
services.AddAzureKeyVaultKeyManagement(
    configuration.GetSection("AzureKeyVault"));

Additional Azure Security

// Via the Dispatch builder (recommended)
services.AddDispatch(dispatch =>
{
    dispatch.UseSecurity(configuration);
});

// Or standalone Azure security setup — the Key Vault credential store and
// Service Bus validation are wired through the Azure security builder.
// The credential store is registered only when a VaultUri is supplied.
services.AddDispatchSecurityAzure(azure =>
{
    azure.VaultUri("https://my-vault.vault.azure.net/")
         .EnableServiceBusValidation();
});

---

HashiCorp Vault

Envelope encryption with HashiCorp Vault Transit secrets engine.

Installation

dotnet add package Excalibur.Compliance.Vault

Setup

// Core connection settings via the fluent builder
services.AddVaultKeyManagement(vault =>
    vault.VaultUri(new Uri("https://vault.example.com:8200"))
         .TransitMountPath("transit")
         .KeyNamePrefix("dispatch-"));   // Keys named: dispatch-{keyId}

// Authentication (and other grouped sub-options) via Configure<VaultOptions>
services.Configure<VaultOptions>(options =>
{
    options.Auth.AuthMethod = VaultAuthMethod.Token;
    options.Auth.Token = "s.your-vault-token";
});

// Or bind the whole VaultOptions from an appsettings "Vault" section
services.AddVaultKeyManagement(vault => vault.BindConfiguration("Vault"));

---

Provider Comparison

Feature	AWS KMS	Azure Key Vault	HashiCorp Vault
Multi-region	AddAwsKmsKeyManagementMultiRegion	Via Azure replication	Via Vault replication
Local development	AddAwsKmsKeyManagementLocalStack	N/A	Dev mode
Configuration binding	Action callback	Action, options, config section	Action, options, config section
Custom client	Factory overload	Via Azure Identity	Token-based

See Also

• Encryption Architecture — Core encryption design and field-level encryption
• Compliance — FedRAMP, HIPAA, SOC2 checklists
• Data Providers — Database-level encryption at rest