Feature: Key Management Service (KMS)

[vishesh92]

Key Management Service (KMS) with HSM Integration

Description

Introduces a Key Management Service (KMS) framework for CloudStack that provides envelope encryption for volume encryption. KEKs (Key Encryption Keys) stored in PKCS#11-compliant HSMs or the CloudStack database wrap per-volume DEKs (Data Encryption Keys), ensuring key material is never stored in plaintext.

Design Document: https://cwiki.apache.org/confluence/display/CLOUDSTACK/Key+Management+Service+%28KMS%29+with+HSM+Integration

New APIs

API	Auth	Description
createKMSKey	All users	Create a KMS key (KEK) bound to an HSM profile
listKMSKeys	All users	List KMS keys
updateKMSKey	All users	Update name, description, or enabled state
deleteKMSKey	All users	Delete a KMS key (if not in use)
rotateKMSKey	Admin	Rotate KEK with optional cross-HSM migration
migrateVolumesToKMS	Admin	Migrate passphrase-encrypted volumes to KMS
addHSMProfile	Admin	Add HSM profile configuration
listHSMProfiles	All users	List available HSM profiles
updateHSMProfile	Admin	Update HSM profile
deleteHSMProfile	Admin	Delete HSM profile

New Database Tables

kms_hsm_profiles, kms_hsm_profile_details, kms_keys, kms_kek_versions, kms_wrapped_key, kms_database_kek_objects

Modified: cloud.volumes — added kms_key_id and kms_wrapped_key_id columns.

New Global Settings

Setting	Default	Description
kms.dek.size.bits	256	DEK size in bits
kms.retry.count	3	Retry attempts for transient failures
kms.retry.delay.ms	1000	Delay between retries
kms.operation.timeout.sec	30	Per-operation timeout
kms.rewrap.batch.size	50	Keys rewrapped per background batch
kms.rewrap.interval.ms	300000	Background rewrap interval

UI Changes

• New KMS top-level menu with KMS Keys and HSM Profiles sub-sections
• KMS key selection in Deploy VM and Create Volume wizards
• HSM profile management restricted to Admin users in UI

How to Test

Tested with:

• SoftHSM2.
• BouncyHSM

# 1. Add an HSM profile (use SoftHSM2 for testing)

# 2. Create a KMS key with HSM profile

# 3. Create a disk offering with Encryption enabled

# 4. Deploy a VM/create a volume and specify the KMS key

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 3.65%. Comparing base (da85858) to head (2357855).

❗ There is a different number of reports uploaded between BASE (da85858) and HEAD (2357855). Click for more details.

HEAD has 1 upload less than BASE

Flag	BASE (da85858)	HEAD (2357855)
unittests	1	0

Additional details and impacted files

@@              Coverage Diff              @@
##               main   #12711       +/-   ##
=============================================
- Coverage     17.93%    3.65%   -14.29%     
=============================================
  Files          5939      455     -5484     
  Lines        533147    38714   -494433     
  Branches      65237     7168    -58069     
=============================================
- Hits          95607     1414    -94193     
+ Misses       426797    37110   -389687     
+ Partials      10743      190    -10553     

Flag	Coverage Δ
uitests	3.65% <ø> (-0.02%)	⬇️
unittests	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This pull request introduces a comprehensive Key Management Service (KMS) framework for CloudStack that provides envelope encryption for volume encryption. KEKs (Key Encryption Keys) stored in PKCS#11-compliant HSMs or the CloudStack database wrap per-volume DEKs (Data Encryption Keys), ensuring key material is never stored in plaintext.

Changes:

• Adds KMS framework with HSM integration for envelope encryption
• Introduces 8 new admin/user APIs for KMS key and HSM profile management
• Creates 6 new database tables for storing KMS metadata
• Adds UI support for KMS key selection in volume and VM deployment workflows

Reviewed changes

Copilot reviewed 123 out of 123 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
framework/kms/	Core KMS framework interfaces and exceptions
plugins/kms/	Database and PKCS#11 KMS provider implementations
engine/schema/	Database entities and DAOs for KMS tables
api/src/main/java/org/apache/cloudstack/api/command/	New API commands for KMS operations
ui/src/views/	UI components for KMS key selection
server/src/main/java/	KMS manager implementation and integration
Test files	Unit tests for KMS retry logic and key creation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.