Skip to main content

Encryption Architecture

Excalibur provides comprehensive encryption capabilities for data at rest and in transit, supporting enterprise compliance requirements including FedRAMP, GDPR, SOC 2, and HIPAA.

Before You Start​

Overview​

The encryption architecture is built on three core components:

ComponentPurposePackage
IEncryptionProviderField-level encryption/decryptionExcalibur.Compliance.Abstractions
IKeyManagementProviderKey lifecycle and rotationExcalibur.Compliance.Abstractions
MessageEncryptionMiddlewarePipeline message encryptionExcalibur.Security

AES-256-GCM Encryption​

The default encryption provider uses AES-256-GCM, providing authenticated encryption with associated data (AEAD).

Technical Specifications​

ParameterValueDescription
AlgorithmAES-256-GCMNIST-approved, FIPS 140-2 compatible
Key Size256 bits (32 bytes)Maximum AES key strength
Nonce Size96 bits (12 bytes)GCM standard, randomly generated
Auth Tag128 bits (16 bytes)Maximum authentication tag size

Basic Usage​

using Excalibur.Compliance;

// Inject IEncryptionProvider
public class MyService
{
private readonly IEncryptionProvider _encryption;

public MyService(IEncryptionProvider encryption)
{
_encryption = encryption;
}

public async Task<EncryptedData> EncryptSensitiveDataAsync(
byte[] plaintext,
CancellationToken ct)
{
var context = new EncryptionContext
{
TenantId = "tenant-123",
Purpose = "pii-field"
};

return await _encryption.EncryptAsync(plaintext, context, ct);
}

public async Task<byte[]> DecryptSensitiveDataAsync(
EncryptedData encrypted,
CancellationToken ct)
{
var context = new EncryptionContext
{
TenantId = "tenant-123"
};

return await _encryption.DecryptAsync(encrypted, context, ct);
}
}

Encryption Context​

The EncryptionContext provides tenant isolation, key selection, and associated authenticated data (AAD):

var context = new EncryptionContext
{
// Key selection
KeyId = "my-encryption-key", // Specific key (optional)
KeyVersion = 3, // Specific version (optional)

// Multi-tenant isolation
TenantId = "tenant-123", // Binds ciphertext to tenant

// Operational metadata
Purpose = "pii-field", // For audit and key selection
Classification = DataClassification.Confidential,

// Additional authenticated data
AssociatedData = Encoding.UTF8.GetBytes("order-123"),

// Compliance
RequireFipsCompliance = true // Enforce FIPS mode
};
Multi-Tenant Security

TenantId is always included in the AAD (Associated Authenticated Data) as a length-prefixed field, even when empty or null. This ensures a stable, unambiguous AAD format across all tenancy modes. When a non-empty TenantId is provided, it cryptographically binds the ciphertext to the tenant -- attempting to decrypt with a different tenant ID will fail authentication, even with the correct key.

Key Management​

Key Lifecycle​

Keys follow a defined lifecycle:

StatusEncryptDecryptDescription
Active✅✅Current key for new encryption
DecryptOnly❌✅Rotated out, can still decrypt old data
PendingDestruction❌❌Awaiting deletion, no operations
Destroyed❌❌Permanently deleted
Suspended❌❌Frozen due to security concern

IKeyManagementProvider Interface​

public interface IKeyManagementProvider
{
// Key retrieval
Task<KeyMetadata?> GetKeyAsync(string keyId, CancellationToken ct);
Task<KeyMetadata?> GetKeyVersionAsync(string keyId, int version, CancellationToken ct);
Task<KeyMetadata?> GetActiveKeyAsync(string? purpose, CancellationToken ct);
Task<IReadOnlyList<KeyMetadata>> ListKeysAsync(KeyStatus? status, string? purpose, CancellationToken ct);

// Key lifecycle
Task<KeyRotationResult> RotateKeyAsync(string keyId, EncryptionAlgorithm algorithm,
string? purpose, DateTimeOffset? expiresAt, CancellationToken ct);
Task<bool> SuspendKeyAsync(string keyId, string reason, CancellationToken ct);
Task<bool> DeleteKeyAsync(string keyId, int retentionDays, CancellationToken ct);
}

Key Management Providers​

In-Memory (Development Only)​

using Excalibur.Compliance;

// Development/testing only — keys are stored in memory
builder.Services.AddDevEncryption();
// Or: builder.Services.AddEncryption(e => e.UseInMemoryKeyManagement("dev"));
Development Only

InMemoryKeyManagementProvider stores keys in memory. Keys are lost on restart. Never use in production.

Azure Key Vault​

using Excalibur.Compliance.Azure;

builder.Services.AddAzureKeyVaultKeyManagement(azure =>
{
azure.VaultUri(new Uri("https://my-vault.vault.azure.net/"))
// Key naming
.KeyNamePrefix("dispatch-encryption-")
// Require Premium (HSM-backed) keys in production
.RequirePremiumTier();
});
// Authentication uses DefaultAzureCredential (Managed Identity, environment,
// or developer credentials) unless a custom TokenCredential is supplied.

AWS KMS​

using Excalibur.Compliance.Aws;

builder.Services.AddAwsKmsKeyManagement(options =>
{
options.Region = "us-east-1";
options.KeyId = "arn:aws:kms:us-east-1:123456789:key/12345678-...";

// Optional: Custom endpoint for LocalStack testing
options.ServiceUrl = configuration["AWS:ServiceUrl"];

// Key alias for rotation
options.KeyAlias = "alias/dispatch-encryption";
});

HashiCorp Vault​

using Excalibur.Compliance.Vault;

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

// Authentication via Configure<VaultOptions> (grouped Auth sub-options)
builder.Services.Configure<VaultOptions>(options =>
{
// Token auth
options.Auth.AuthMethod = VaultAuthMethod.Token;
options.Auth.Token = configuration["Vault:Token"];

// Or AppRole auth
// options.Auth.AuthMethod = VaultAuthMethod.AppRole;
// options.Auth.AppRoleId = configuration["Vault:RoleId"];
// options.Auth.AppRoleSecretId = configuration["Vault:SecretId"];
});

Message-Level Encryption​

MessageEncryptionMiddleware​

The middleware provides transparent encryption/decryption in the dispatch pipeline:

using Excalibur.Security;

builder.Services.AddDispatch();
builder.Services.AddMessageEncryption(options =>
{
options.Enabled = true;
options.EncryptByDefault = false; // Only encrypt marked messages
options.DefaultAlgorithm = EncryptionAlgorithm.Aes256Gcm;
options.ExcludedMessageTypes = new HashSet<string> { "HealthCheckQuery" };
});

ISensitiveMessage Marker​

Mark messages containing sensitive data for automatic encryption:

using Excalibur.Security;

// Messages implementing ISensitiveMessage are automatically encrypted
public class CreatePatientAction : IDispatchAction, ISensitiveMessage
{
public string FirstName { get; set; }
public string LastName { get; set; }
public string SSN { get; set; } // Sensitive!
}

// Regular messages are not encrypted by default
public class GetOrderAction : IDispatchAction<Order>
{
public Guid OrderId { get; set; }
}

Pipeline Behavior​

Field-Level Encryption​

[PersonalData] Attribute​

Mark fields for automatic encryption at rest:

using Excalibur.Compliance;

public class Patient
{
public Guid Id { get; set; }

[PersonalData] // Encrypted at rest
public string FirstName { get; set; }

[PersonalData]
public string LastName { get; set; }

[PersonalData]
[Sensitive] // Additional classification
public string SSN { get; set; }

public DateTime DateOfBirth { get; set; } // NOT encrypted
}

[EncryptedField] Attribute​

For more control over field encryption:

using Excalibur.Compliance;

public class PaymentInfo
{
// byte[] only. The encrypting decorators select byte[] properties; the
// attribute on a string compiles and is then skipped, so serialize to
// bytes yourself before the value is stored.
[EncryptedField(Purpose = "payment-data")]
public byte[] CardNumber { get; set; }

[EncryptedField(Purpose = "payment-data")]
public byte[] CVV { get; set; }
}

Encrypting Store Decorators​

Transparent encryption for persistence layers using the decorator pattern:

Event Store Encryption​

// AddEventSourcingCryptoShredding wires the encrypting decorators across the event
// store, inbox and outbox. Behaviour is configured on EncryptionOptions.
builder.Services.AddEncryption(encryption => encryption
.UseKeyManagement<AesGcmEncryptionProvider>("primary")
.ConfigureOptions(options =>
{
options.Mode = EncryptionMode.EncryptAndDecrypt;
options.DefaultPurpose = "event-data";
}));

builder.Services.AddEventSourcingCryptoShredding();

Encryption Modes​

ModeWrite BehaviorRead BehaviorUse Case
EncryptAndDecryptEncrypt allDecrypt allNormal operation
EncryptNewDecryptAllEncrypt newDecrypt old & newAfter migration
DecryptOnlyWritePlaintextWrite plaintextDecrypt if encryptedDuring migration
DecryptOnlyReadOnlyReject writesDecrypt onlyMaintenance mode
DisabledPass throughPass throughTesting/debugging

Available Decorators​

DecoratorPackagePurpose
EncryptingEventStoreDecoratorExcalibur.EventSourcingEvent store encryption
EncryptingProjectionStoreDecoratorExcalibur.EventSourcingProjection encryption
EncryptingInboxStoreDecoratorExcalibur.ComplianceInbox message encryption
EncryptingOutboxStoreDecoratorExcalibur.ComplianceOutbox message encryption

Inbox and outbox registration​

Register all inbox and outbox implementations before calling AddInboxEncryption or AddOutboxEncryption. These helpers cover independent unkeyed registrations as well as provider and "default" keyed registrations. Forwarding aliases reuse the decorated result; independently registered stores receive their own layer. Public registration order, service keys and lifetimes remain unchanged. A store registered later is not covered by an earlier decoration call, so keep encryption decoration after store registration in the composition root.

For custom DecorateKeyedStores factories, respect the original store's disposal ownership. Instances supplied by the caller remain caller-owned; disposable type/factory activations remain container-owned. Return a non-owning wrapper rather than a borrowed disposable instance unchanged. Use asynchronous scope/provider disposal when an owned store implements only IAsyncDisposable. As with ordinary container aliases, disposal implementations must be idempotent.

Outbox caller ownership​

For preencoded outbox writes, EncryptAndDecrypt and EncryptNewDecryptAll encrypt an owned snapshot rather than replacing the caller's payload. Ordinary Stage, multi-transport Stage and the atomic sent-plus-inbox batch route capture payload bytes, scalar fields, dictionary containers and transport records before encryption awaits. Retrying the same caller envelope therefore starts from its plaintext, including after an encryption or inner-store failure. Nested objects inside headers/metadata retain their existing value semantics; this is not recursive cloning of arbitrary application object graphs.

DecryptOnlyWritePlaintext and Disabled retain their pass-through envelope/payload/transport references. DecryptOnlyReadOnly rejects these writes before copying or enumerating caller transports. An undefined mode is rejected before encryption, enumeration or inner writes; it never silently selects plaintext. Each write captures its mode once. Changing configuration affects later writes, not an in-flight write's chosen behavior. Read behavior and typed completion/capability forwarding remain separate from this payload-ownership boundary.

Legacy EnqueueAsync keeps serialization and envelope construction inside the owning provider. Encrypting modes require its optional IOutboxPayloadTransformStore capability, so encryption receives the exact serialized bytes and prepared record tenant before any row is accepted. A missing capability refuses the legacy write with an actionable error; it never substitutes generic JSON or stores plaintext. Preencoded StageMessageAsync remains available without this legacy capability. The raw transform writer is deliberately hidden by the encryption decorator to prevent callers bypassing encryption.

The provider copies callback-owned output before persistence and checks cancellation after the callback, before accepting the write. Callback failure/cancellation causes no accepting row mutation. Cancellation racing with persistence retains that provider's existing transaction and uncertainty semantics. This capability retains the legacy serialization warnings; it is not a NativeAOT certification.

Tenant Binding in the Store Decorators​

The decorators build the EncryptionContext for you, per record, and bind a tenant into the AAD. Which tenant depends on whether the record carries one:

DecoratorTenant bound on writeTenant bound on read
EncryptingOutboxStoreDecoratorthe message's TenantIdthe stored message's TenantId
EncryptingInboxStoreDecoratorthe ambient tenant (the one the inbox store stamps on the entry)the stored entry's TenantId
EncryptingProjectionStoreDecoratorthe ambient tenantthe ambient tenant
EncryptingEventStoreDecoratornot applicable (personal fields use per-subject keys)the ambient tenant
  • Outbox and inbox bind the record's own tenant on read, never the reader's ambient tenant. Both are drained for every tenant by background processors that run outside any tenant scope, so the record's tenant is the only value that can be re-derived at drain time. A payload moved into a row carrying a different tenant fails authentication.
  • A record with no tenant (null, empty, or whitespace) binds the reserved untenanted partition value, the same value the store returns for it on read.
  • Ambient context is separate from record ownership. Decorators that consume ITenantContext receive the configured tenant context. Outbox writes and drains bind the message's own TenantId; the outbox decorator does not require an ambient request tenant to drain records for different tenants.
  • Keys are not per tenant on these paths. One active key per purpose serves every tenant, so the AAD tenant is the only cryptographic tenant separation the decorators provide. Authorization and each store's query scope remain separate controls. Outbox workers and GetAllTenants administration are estate-wide, so this AAD binding does not turn those operations into tenant-confined queries.

Mixed-Mode Migration​

The decorators support seamless migration from plaintext to encrypted data:

// Phase 1: Start encrypting new data, decrypt both old and new
builder.Services.Configure<EncryptionOptions>(o =>
o.Mode = EncryptionMode.EncryptNewDecryptAll);

// Phase 2: Run background re-encryption job
// (See Key Rotation section below)

// Phase 3: All data encrypted, normal operation
builder.Services.Configure<EncryptionOptions>(o =>
o.Mode = EncryptionMode.EncryptAndDecrypt);
});

Key Rotation​

IReEncryptionService​

Re-encrypt data when keys rotate:

using Excalibur.Compliance;

public class KeyRotationJob : BackgroundService
{
private readonly IReEncryptionService _reEncryption;
private readonly IKeyManagementProvider _keyManagement;

protected override async Task ExecuteAsync(CancellationToken ct)
{
// Rotate key
var result = await _keyManagement.RotateKeyAsync(
keyId: "my-key",
algorithm: EncryptionAlgorithm.Aes256Gcm,
purpose: "event-data",
expiresAt: DateTimeOffset.UtcNow.AddDays(90),
ct);

// Re-encrypt existing data with new provider
var options = new ReEncryptionOptions
{
SourceProviderId = "old-provider",
TargetProviderId = "new-provider",
BatchSize = 1000,
ContinueOnError = true
};

var processed = 0;
await foreach (var item in _reEncryption.ReEncryptBatchAsync(
GetEntitiesAsync(), options, ct))
{
if (item.Success)
processed += item.FieldsReEncrypted;
}

_logger.LogInformation("Re-encrypted {Count} fields", processed);
}
}

Lazy Re-Encryption​

Configure lazy migration to automatically re-encrypt plaintext data on read/write:

using Excalibur.Compliance;

builder.Services.Configure<EncryptionOptions>(options =>
{
options.LazyMigrationEnabled = true;
options.LazyMigrationMode = LazyMigrationMode.OnRead;
});

FIPS 140-2 Compliance​

Validation​

// Check if running in FIPS mode
var provider = serviceProvider.GetRequiredService<IEncryptionProvider>();
var isFipsCompliant = await provider.ValidateFipsComplianceAsync(ct);

if (!isFipsCompliant)
{
_logger.LogWarning("System is not running in FIPS 140-2 mode");
}

Configuration​

builder.Services.AddEncryption(options =>
{
options.RequireFipsComplianceByDefault = true;
});

// Per-operation enforcement
var context = new EncryptionContext
{
RequireFipsCompliance = true // Throws if not FIPS compliant
};

Platform Requirements​

PlatformFIPS Mode
WindowsRegistry value FipsAlgorithmPolicy under HKLM\SYSTEM\CurrentControlSet\Control\Lsa
Linux/proc/sys/crypto/fips_enabled = 1
AzureAzure FIPS-enabled VMs
AWSAWS GovCloud, FIPS endpoints

How detection works​

On Windows, FIPS status is read from the FipsAlgorithmPolicy registry value named above. On Linux it is read from /proc/sys/crypto/fips_enabled.

Re-generate Windows compliance evidence produced by an earlier version

Detection previously read CryptoConfig.AllowOnlyFipsAlgorithms. .NET Core and later pin that property to false and never populate it from the host policy, so every Windows host reported not FIPS compliant, including one genuinely running under FIPS policy. That result feeds the SOC 2 encryption control validator, so evidence generated on a Windows host you believe is FIPS-enabled recorded a false negative. Re-generate it.

Unconfirmed is not the same as disabled​

FipsDetectionResult carries a boolean IsFipsEnabled and a ValidationDetails string, and there are three outcomes rather than two:

OutcomeIsFipsEnabledWhat it means
Policy ontrueThe host policy enables FIPS.
Policy offfalseThe host policy is present and disabled — a deployment decision.
Policy unreadablefalseThe value is absent or inaccessible. ValidationDetails states that compliance is unconfirmed.

The third outcome reports false because the check cannot assert compliance it did not establish — but it is a different problem from a policy deliberately turned off. Read ValidationDetails, not only the boolean. An unconfirmed result usually means the process cannot read the registry key and is an operational fault to resolve; reporting it as a settled not compliant would assert something the check never determined.

AesGcmEncryptionProvider resolves this through the detector rather than reading the runtime property itself, so the provider and the compliance report cannot disagree. It accepts an optional IFipsDetector; hosts that supply none are unaffected.

Crypto-Shredding (GDPR)​

For GDPR right-to-erasure compliance, delete the encryption key to render all data unrecoverable:

// Crypto-shredding for GDPR compliance
public class GdprErasureHandler
{
private readonly IKeyManagementProvider _keyManagement;

public async Task ExecuteErasureAsync(string userId, CancellationToken ct)
{
// User's data was encrypted with a user-specific key
var userKeyId = $"user-{userId}-pii";

// Delete the key - all encrypted data becomes unrecoverable
await _keyManagement.DeleteKeyAsync(
keyId: userKeyId,
retentionDays: 7, // Grace period for recovery
ct);
}
}

Compliance Mapping​

FeatureFedRAMPGDPRSOC 2HIPAA
AES-256-GCMSC-28Art 32C2§164.312(a)(2)(iv)
Key rotationSC-12Art 32C2§164.312(a)(2)(iv)
Tenant isolationAC-4Art 25CC5§164.312(a)(1)
FIPS complianceSC-13--§164.312(a)(2)(iv)
Crypto-shredding-Art 17C3Disposal
Audit loggingAU-3Art 30CC4§164.312(b)

Best Practices​

Do​

  • Use tenant-specific encryption contexts for multi-tenant applications
  • Rotate keys regularly (90 days recommended)
  • Enable FIPS mode for government/healthcare workloads
  • Use cloud KMS (Azure Key Vault, AWS KMS) in production
  • Test key rotation and re-encryption procedures

Don't​

  • Store encryption keys in code or configuration files
  • Use InMemoryKeyManagementProvider in production
  • Skip AAD (Associated Authenticated Data) for tenant-bound data
  • Ignore DecryptOnly keys - they contain historical data
  • Delete keys without a retention period

See Also​

  • Encryption Providers — Detailed configuration for AES-GCM, Azure Key Vault, AWS KMS, and HashiCorp Vault providers
  • Authorization & Audit (A3) — Activity-based authorization and access control for encrypted resources
  • Data Masking — Field-level data masking and PII redaction for compliance