Advanced Encryption Capabilities: BYOK, HSM, and Key Management

[JayVDZ]

Summary

Review and implement advanced encryption key management options for customers with stricter security requirements.

Background

Issue #171 implemented credential encryption at rest using ASP.NET Core Data Protection with:

• AES-256-GCM encryption (FIPS-approved)
• JIM-managed file-based key storage
• Shared key path for multi-container deployments
• Environment variable override (JIM_ENCRYPTION_KEY_PATH)

This issue tracks implementation options for customers requiring more advanced key management capabilities.

Related Issues

• Encrypt connector credential passwords at rest #171 - Encrypt connector credential passwords at rest (completed)
• FIPS 140-2/140-3 Compliance for Credential Encryption #256 - FIPS 140-2/140-3 Compliance for Credential Encryption

Requirements to Review

1. Bring Your Own Key (BYOK)

• Customer provides their own encryption key
• Key can be provided via:
  • File path (key file with restricted permissions)
  • Environment variable
• Validation of key format and strength
• Documentation for key generation requirements

2. Hardware Security Module (HSM) Integration

JIM is primarily designed for air-gapped environments. HSM integration options should prioritise on-premises solutions used in government, defence, and regulated industries.

On-Premises HSM Options (Priority)

Vendor	Interface	Common In	Notes
Thales Luna (formerly SafeNet)	PKCS#11, Microsoft CNG	UK/US Government, Defence, Finance	Luna Network HSM, Luna PCIe
Utimaco	PKCS#11, Microsoft CNG	European Government, Finance	SecurityServer, CryptoServer
nCipher/Entrust nShield	PKCS#11, Microsoft CNG	UK Government (NCSC certified), Finance	nShield Connect, nShield Solo
AWS CloudHSM	PKCS#11	Organisations with AWS presence	Dedicated HSM in AWS VPC, FIPS 140-2 Level 3
Fortanix	PKCS#11, REST API	Modern deployments	Software-defined HSM option available
YubiHSM	PKCS#11	Smaller deployments, development	Cost-effective, compact form factor

Cloud Key Management (Optional/Secondary)

For customers with cloud presence who don't require air-gapped deployment:

• Azure Key Vault (Managed HSM tier for FIPS 140-2 Level 3)
• AWS KMS
• Google Cloud KMS
• HashiCorp Vault (can use HSM backend)

Implementation Approach

// PKCS#11 is the common interface for most enterprise HSMs
// Custom IXmlRepository implementation for HSM key storage
public class Pkcs11XmlRepository : IXmlRepository
{
    private readonly IPkcs11Library _pkcs11;
    private readonly string _tokenLabel;
    private readonly string _keyLabel;
    
    // Store Data Protection keys in HSM
    public void StoreElement(XElement element, string friendlyName) { ... }
    public IReadOnlyCollection<XElement> GetAllElements() { ... }
}

Microsoft CNG Provider Option

For Windows environments with HSM vendors that provide CNG providers:

// Use HSM via Windows CNG (Cryptography Next Generation)
dataProtection.ProtectKeysWithDpapiNG(
    $"CERTIFICATE=HashId:{thumbprint}", 
    DpapiNGProtectionDescriptorFlags.None);

3. Key Lifecycle Management

• Key rotation procedures
• Key backup and recovery
• Key revocation
• Re-encryption of existing credentials with new key

4. Guided Setup Integration

• First-run wizard encryption configuration step
• Admin UI for viewing encryption settings
• Clear guidance on key management options

Technical Approach

ASP.NET Core Data Protection is designed for extensibility:

// Current: File-based key storage
dataProtection.PersistKeysToFileSystem(new DirectoryInfo(keyPath));

// Future: PKCS#11 HSM (Thales, Utimaco, nCipher, etc.)
dataProtection.AddKeyManagementOptions(o => 
    o.XmlRepository = new Pkcs11XmlRepository(pkcs11Config));

// Future: Azure Key Vault (for cloud deployments)
dataProtection.PersistKeysToAzureBlobStorage(...)
              .ProtectKeysWithAzureKeyVault(...);

Upgrade Path (from Issue #171 Analysis)

Scenario	Customer Impact	Migration Required?
File → HSM key storage	Low	No - old keys can be imported to HSM
File → Azure Key Vault	Low	No - extensible via IXmlRepository
Add BYOK support	None	No - new deployment option

Acceptance Criteria

1. BYOK option documented and tested
2. At least one on-premises HSM integration available (PKCS#11 recommended)
3. Key rotation documented with procedures
4. Upgrade path from file-based keys to HSM verified
5. Setup wizard includes encryption configuration (if implemented)

Air-Gapped Deployment Requirement

JIM must support fully air-gapped deployments. This means:

• All encryption functionality must work without network access
• Cloud-based key management (Azure Key Vault, AWS KMS) must be optional
• On-premises HSM support via PKCS#11 or CNG is the primary enterprise option
• File-based key storage remains the default for simpler deployments

References

• ASP.NET Core Data Protection Key Storage Providers
• PKCS#11 Specification
• Thales Luna HSM
• Utimaco HSM
• Entrust nShield HSM
• UK NCSC - Using HSMs
• Parent issue: Encrypt connector credential passwords at rest #171

---

🤖 Generated with Claude Code