A production-ready, high-performance key management library for .NET 9.0 applications with built-in caching, versioning, automatic rotation, and comprehensive health monitoring.
Overview
Feedemy.KeyManagement provides a secure, scalable solution for managing cryptographic keys and sensitive configuration values in enterprise .NET applications. It combines platform-specific secure storage with advanced features like automatic key rotation, version management, distributed caching, and full audit trails.
High Performance: Cache-first architecture with Redis/Memory cache support and multi-layer caching
Automatic Rotation: Background service with configurable rotation policies and health monitoring
Version Management: Complete key version history with rollback capabilities and deactivation
Health Monitoring: Built-in health checks, rotation warnings, and system diagnostics
Admin Operations: Comprehensive admin API for complete key lifecycle management
Master Key Encryption: Optional envelope encryption for ENV keys using master EncryptionKey
Distributed Cache Invalidation: Pub/sub pattern for multi-server cache synchronization
Cache Warming: Automatic preloading of critical keys after invalidation
Audit Trail: Full audit logging for all administrative operations
Test Coverage: 412 automated unit + integration tests exercise RSA/ECDSA workflows, master-key re-encryption, cache invalidation paths, and storage fallbacks. Latest dotnet test tests/Feedemy.KeyManagement.IntegrationTests run (2025‑02‑14) completed in ~64s with 411 passing and 1 known failure (see below).
Current Test Status
Failing scenario: (). The assertion still expects a 32-byte plaintext buffer, but the storage pipeline is returning the 60-byte master-key-encrypted payload when cache serves the item. We need to ensure the retrieval path always flows through (e.g., by enforcing for cache hits) so the decrypted data length matches the metadata contract.
# For Entity Framework Core persistence
dotnet add package Feedemy.KeyManagement.Providers.EntityFramework
# For Windows DPAPI storage
dotnet add package Feedemy.KeyManagement.Providers.Windows
# For Linux KeyRing storage
dotnet add package Feedemy.KeyManagement.Providers.Linux
# For Azure Key Vault storage
dotnet add package Feedemy.KeyManagement.Providers.Azure
Quick Start
Basic Setup (InMemory - Development)
using Feedemy.KeyManagement.Extensions;
using Microsoft.Extensions.DependencyInjection;
// Program.cs or Startup.cs
services.AddKeyManagement(options =>
{
options.EnableAutoRotation = true;
options.RotationCheckInterval = TimeSpan.FromHours(6);
options.DefaultRotationDays = 90;
})
.UseInMemoryStorage() // Development only
.UseMemoryCache() // Development only
.UseInMemoryPersistence() // Development only
.AddConsoleNotifications();
Uses Azure Key Vault for cloud-based secure storage. Best for cloud deployments.
Auto-Detection
.UseAutoStorage() // Automatically selects Windows/Linux based on OS
Cache Providers
Cache providers accelerate key retrieval with multi-layer caching:
Memory Cache (Development)
.UseMemoryCache()
In-memory caching using IMemoryCache. Fast but not distributed.
Redis Cache (Production)
.UseRedisCache("localhost:6379")
Distributed caching with Redis. Supports pub/sub for cache invalidation across multiple servers.
Null Cache (Testing)
.UseNullCache()
No caching - always reads from storage. Useful for testing cache-miss scenarios.
Persistence Providers
Persistence providers store key metadata, versions, and audit logs:
InMemory (Development)
.UseInMemoryPersistence()
In-memory storage. Lost on restart. Development only.
Entity Framework Core (Production)
.UseEntityFramework()
Stores data in SQL Server (or any EF Core provider) using your existing DbContext.
Migration Setup:
# Add migration
dotnet ef migrations add AddKeyManagement
# Apply migration
dotnet ef database update
Required entities automatically added:
KeyMetadata - Key configuration and current version
KeyVersion - Version history with content hashes
KeyAuditLog - Full audit trail of admin operations
Features
Key Retrieval (Cache-First Strategy)
The retrieval system uses a three-tier cache strategy for maximum performance:
// Fast path: Cache hit (< 1ms)
var key = await _keyManagement.RetrieveKeyAsync("MyKey");
// Cache layers checked in order:
// 1. Content cache (key content)
// 2. Metadata cache (key metadata)
// 3. Version cache (version info)
// 4. Storage layer (if cache miss)
Performance characteristics:
Cache hit: < 1ms
Cache miss (storage): 10-50ms
Database fallback: 50-200ms
Retrieve by version:
// Get specific version
var key = await _keyManagement.RetrieveKeyByVersionAsync("MyKey", version: 3);
Retrieve using enum (type-safe):
// Define in your code
public enum KeyName
{
EncryptionKey,
ApiKey,
JwtSigningKey
}
// Retrieve
var key = await _keyManagement.RetrieveKeyAsync(KeyName.EncryptionKey);
Key Rotation
Manual Rotation
// Update key content (creates new version)
var result = await _adminService.UpdateKeyContentAsync(
keyName: "ApiKey",
newContent: newKeyBytes,
reason: "Scheduled rotation",
updatedBy: "RotationService"
);
Console.WriteLine($"Rotated to version {result.Data.CurrentVersion}");
Automatic Rotation
The background service automatically rotates keys based on configured intervals:
// Enable in configuration
services.AddKeyManagement(options =>
{
options.EnableAutoRotation = true;
options.RotationCheckInterval = TimeSpan.FromHours(6); // Check every 6 hours
});
// Per-key configuration
await _adminService.CreateKeyAsync(new CreateKeyRequest
{
KeyName = "ApiKey",
RotationIntervalDays = 90, // Rotate every 90 days
AutoRotationEnabled = true, // Enable auto-rotation for this key
// ...
});
Rotation behavior:
Background service runs every RotationCheckInterval
Checks all keys with AutoRotationEnabled = true
Rotates keys where NextRotationDue <= Now
Automatically invalidates all cache layers
Triggers cache warming for critical keys
Logs all rotation events to audit trail
Monitor Rotation Status
var status = await _adminService.GetRotationServiceStatusAsync();
Console.WriteLine($"Service Running: {status.IsRunning}");
Console.WriteLine($"Last Check: {status.LastCheckTime}");
Console.WriteLine($"Next Check: {status.NextCheckTime}");
Console.WriteLine($"Keys Pending Rotation: {status.KeysPendingRotation.Count}");
foreach (var key in status.KeysPendingRotation)
{
Console.WriteLine($" - {key.KeyName}: Due {key.NextRotationDue}");
}
Version Management
Version History
// Get all versions
var versions = await _keyManagement.GetKeyVersionsAsync("ApiKey");
foreach (var version in versions)
{
Console.WriteLine($"Version {version.Version}: Created {version.CreatedAt}");
Console.WriteLine($" Status: {version.Status}");
Console.WriteLine($" Active: {version.IsActive}");
}
// Get current version number
var currentVersion = await _keyManagement.GetCurrentVersionAsync("ApiKey");
Rollback
Rollback to a previous version when needed:
// Rollback to version 3
var result = await _adminService.RollbackToVersionAsync(
keyName: "ApiKey",
targetVersion: 3,
reason: "Revert to stable version after incident",
performedBy: "AdminUser"
);
if (result.Success)
{
Console.WriteLine($"Rolled back from v{result.Data.FromVersion} to v{result.Data.ToVersion}");
Console.WriteLine($"Deactivated versions: {string.Join(", ", result.Data.DeactivatedVersions)}");
}
Rollback behavior:
Sets target version as current active version
Deactivates all versions newer than target
Invalidates all cache layers (content, metadata, versions)
Triggers cache warming
Creates audit log entry
Version Deactivation
// Deactivate old version (cannot deactivate current version)
await _adminService.DeactivateVersionAsync(
keyName: "ApiKey",
version: 1,
reason: "Old version no longer needed",
performedBy: "AdminUser"
);
// Reactivate version if needed
await _adminService.ReactivateVersionAsync(
keyName: "ApiKey",
version: 1,
performedBy: "AdminUser"
);
Health Monitoring
Key Health
var health = await _keyManagement.GetKeyHealthAsync("ApiKey");
switch (health.Status)
{
case KeyHealthStatus.Healthy:
// Key is fresh (> 7 days from rotation)
break;
case KeyHealthStatus.Warning:
// Key approaching rotation (< 7 days)
Console.WriteLine($"Warning: Rotation due in {health.DaysUntilRotation} days");
break;
case KeyHealthStatus.NeedsRotation:
// Key is overdue for rotation
Console.WriteLine("Critical: Key needs immediate rotation");
break;
case KeyHealthStatus.Inactive:
// Key is deactivated
break;
}
using Feedemy.KeyManagement.Persistence.EntityFramework;
public class ApplicationDbContext : DbContext
{
// ... existing DbSets
// Add KeyManagement entities
public DbSet<KeyMetadata> KeyMetadata { get; set; }
public DbSet<KeyVersion> KeyVersions { get; set; }
public DbSet<KeyAuditLog> KeyAuditLogs { get; set; }
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
base.OnModelCreating(modelBuilder);
// Apply KeyManagement configurations
modelBuilder.ApplyConfigurationsFromAssembly(
typeof(KeyManagementDbContext).Assembly);
}
}
4. Create Migration
dotnet ef migrations add AddKeyManagement
dotnet ef database update
5. Update Code References
Key retrieval:
// Before
var key = await _keyRepository.GetKeyAsync("EncryptionKey");
// After
var key = await _keyManagement.RetrieveKeyAsync("EncryptionKey");
Admin operations:
// Before
await _keyRepository.CreateKeyAsync(new Key { ... });
// After
await _adminService.CreateKeyAsync(new CreateKeyRequest { ... });
6. Adapter Pattern (Optional)
If you need backward compatibility during migration:
public class KeyManagementAdapter : IKeyRepository // Old interface
{
private readonly IKeyManagementService _keyManagement;
private readonly IKeyManagementAdminService _adminService;
public async Task<byte[]> GetKeyAsync(string keyName)
{
return await _keyManagement.RetrieveKeyAsync(keyName);
}
public async Task CreateKeyAsync(Key key)
{
await _adminService.CreateKeyAsync(new CreateKeyRequest
{
KeyName = key.Name,
Content = key.Content,
// ... map properties
});
}
// ... implement other methods
}
Breaking Changes
Cache layer now mandatory: Old code bypassed cache, new code is cache-first
Version management: All keys now have versions (old code was single-version)
Master key encryption: Now optional (configure via RequiresMasterKeyEncryption)
Audit logs: Now built-in (old code had limited logging)
Health monitoring: New feature (no equivalent in old code)
Contributing
Development Setup
# Clone repository
git clone https://github.com/feedemy/keymanagement.git
cd keymanagement
# Restore packages
dotnet restore
# Build solution
dotnet build
# Run all tests
dotnet test
Code Style
Follow .NET coding conventions
Use nullable reference types
Add XML documentation for public APIs
Write unit tests for new features
Update integration tests for workflows
Pull Request Process
Create feature branch from main
Implement feature with tests
Ensure all tests pass: dotnet test
Update README if adding features
Submit PR with description
License
MIT License
Copyright (c) 2025 Feedemy
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Documentation
Architecture Guide - System architecture, data flows, and component diagrams
Migration Guide - Step-by-step migration from legacy systems
Redis Setup Guide - Detailed Redis configuration and troubleshooting