Feature: Key Management Service (KMS) by vishesh92 · Pull Request #12711 · apache/cloudstack

vishesh92 · 2026-02-26T06:20:32Z

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
Docs PR: apache/cloudstack-documentation#634

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:

# 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 · 2026-02-26T07:12:27Z

Codecov Report

❌ Patch coverage is 18.45926% with 2752 lines in your changes missing coverage. Please review.
✅ Project coverage is 18.74%. Comparing base (be51948) to head (7410669).
⚠️ Report is 16 commits behind head on main.

Files with missing lines	Patch %	Lines
...java/org/apache/cloudstack/kms/KMSManagerImpl.java	34.21%	718 Missing and 32 partials ⚠️
...udstack/kms/provider/pkcs11/PKCS11HSMProvider.java	13.32%	428 Missing and 8 partials ⚠️
...e/cloudstack/kms/provider/DatabaseKMSProvider.java	0.00%	145 Missing ⚠️
...apache/cloudstack/api/response/KMSKeyResponse.java	0.00%	115 Missing ⚠️
.../kms/provider/database/KMSDatabaseKekObjectVO.java	0.00%	106 Missing ⚠️
.../main/java/org/apache/cloudstack/kms/KMSKeyVO.java	19.46%	91 Missing ⚠️
...he/cloudstack/api/response/HSMProfileResponse.java	23.85%	83 Missing ⚠️
...n/java/org/apache/cloudstack/kms/HSMProfileVO.java	0.00%	76 Missing ⚠️
...ava/org/apache/cloudstack/kms/KMSWrappedKeyVO.java	11.53%	68 Missing and 1 partial ⚠️
...stack/engine/orchestration/VolumeOrchestrator.java	8.92%	50 Missing and 1 partial ⚠️
... and 51 more

Additional details and impacted files

@@ Coverage Diff @@## main #12711 +/- ##
============================================
+ Coverage 18.10% 18.74% +0.63% - Complexity 16750 18063 +1313 
============================================
Files 6037 6189 +152 Lines 542798 556031 +13233 Branches 66457 67678 +1221 ============================================
+ Hits 98298 104247 +5949 - Misses 433453 440338 +6885 - Partials 11047 11446 +399

Flag	Coverage Δ
uitests	`3.51% <ø> (-0.01%)`	⬇️
unittests	`19.94% <18.45%> (+0.66%)`	⬆️

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

☔ View full report in Codecov by Harness.
📢 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.

blueorangutan · 2026-02-26T13:44:04Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 16962

Copilot

Pull request overview

Copilot reviewed 124 out of 124 changed files in this pull request and generated 8 comments.

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

vishesh92 · 2026-03-04T08:41:41Z

@blueorangutan package

blueorangutan · 2026-03-04T08:44:04Z

@vishesh92 a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-03-04T09:36:20Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 16998

vishesh92 · 2026-03-05T06:59:04Z

@blueorangutan package

blueorangutan · 2026-03-05T07:00:04Z

@vishesh92 a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-03-05T07:52:47Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 17008

vishesh92 · 2026-06-08T09:49:32Z

@blueorangutan package

blueorangutan · 2026-06-08T09:50:04Z

@vishesh92 a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-06-08T10:38:00Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 18184

vishesh92 · 2026-06-08T11:10:06Z

@blueorangutan test

blueorangutan · 2026-06-08T11:12:04Z

@vishesh92 a [SL] Trillian-Jenkins test job (ol8 mgmt + kvm-ol8) has been kicked to run smoke tests

blueorangutan · 2026-06-09T02:28:58Z

[SF] Trillian test result (tid-16259)
Environment: kvm-ol8 (x2), zone: Advanced Networking with Mgmt server ol8
Total time taken: 52077 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr12711-t16259-kvm-ol8.zip
Smoke tests completed. 152 look OK, 0 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File

vishesh92 · 2026-06-09T15:03:19Z

@blueorangutan package

blueorangutan · 2026-06-09T15:10:05Z

@vishesh92 a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-06-09T15:55:28Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 18207

vishesh92 · 2026-06-10T10:13:00Z

@blueorangutan package

blueorangutan · 2026-06-10T10:14:05Z

@vishesh92 a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-06-10T10:59:55Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 18214

kiranchavala

LGTM

Tested the HSM, and kms key generation feature with Bouncy Castle, Soft HSM and the internal database HSM provider .

https://github.com/harrison314/BouncyHsm
https://github.com/softhsm/SoftHSMv2

Test Case Execution	Result
Test the api addHSMProfile	Pass
Test the api listHSMProfiles	Pass
Test the api updateHSMProfile	Pass
Test the api deleteHSMProfile	Pass
Test the createKMSKey api call	Pass
Test the api call listKMSKeys	Pass
Test the api call updateKMSKey	Pass
Test the api call rotateKMSKey	Pass
Test the api call deleteKMSKey	Pass
Test the api call migrateVolumesToKMS	Pass
Test the creation of kms key from the database provider	Pass
Deploy VM with encrypted root and data volume using KMS key	Pass
Deploy VM with encrypted root volume using KMS key from database provider	Pass
Deploy VM with encrypted root volume using legacy encryption	Pass
Background rewrap processes wrapped keys in batches	Pass
validation of kms.dek.size.bits	Pass
KMS operation retries on transient failure	Pass
Perform stop/start/migrate of the vm deployed with kms key	Pass
Change the hsm profile of a kms key	Pass
Test the kms key and hsm profile events	Pass

The kms key option is provided when deploying vm and also when creating a data volume.

weizhouapache · 2026-06-23T14:37:23Z

@harikrishna-patnala
can you review ?

weizhouapache · 2026-06-23T14:37:28Z

@blueorangutan package

blueorangutan · 2026-06-23T14:38:05Z

@weizhouapache a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

weizhouapache · 2026-06-23T14:38:55Z

this is ready for review

@blueorangutan package

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

weizhouapache · 2026-06-23T14:39:46Z

@harikrishna-patnala
could you please review ?

blueorangutan · 2026-06-23T15:57:04Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 18347

DaanHoogland · 2026-06-24T05:52:03Z

@blueorangutan test

blueorangutan · 2026-06-24T05:54:04Z

@DaanHoogland a [SL] Trillian-Jenkins test job (ol8 mgmt + kvm-ol8) has been kicked to run smoke tests

blueorangutan · 2026-06-24T21:41:21Z

[SF] Trillian test result (tid-16421)
Environment: kvm-ol8 (x2), zone: Advanced Networking with Mgmt server ol8
Total time taken: 53060 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr12711-t16421-kvm-ol8.zip
Smoke tests completed. 152 look OK, 0 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File

harikrishna-patnala

LGTM

boring-cyborgBot added component:api component:build labels Feb 26, 2026

vishesh92 force-pushed the feature-kms branch from 0a283c9 to 5112eeaCompare February 26, 2026 06:57

vishesh92 force-pushed the feature-kms branch from ceb2913 to d629f87Compare February 26, 2026 07:39

vishesh92 requested a review from Copilot February 26, 2026 07:39

Copilotstarted reviewing on behalf of vishesh92 February 26, 2026 07:40 View session

CopilotAI reviewed Feb 26, 2026
View reviewed changes

vishesh92 changed the title ~~Feature kms~~Feature: Key Management Service (KMS)Feb 26, 2026

vishesh92 force-pushed the feature-kms branch from ba00a5d to 943f19aCompare February 26, 2026 12:39

apache deleted a comment from blueorangutan Feb 26, 2026

weizhouapache added this to the 4.23.0 milestone Feb 26, 2026

vishesh92 force-pushed the feature-kms branch 3 times, most recently from 8ea09bb to df2df4bCompare March 2, 2026 10:36

vishesh92 requested a review from Copilot March 2, 2026 11:40

Copilotstarted reviewing on behalf of vishesh92 March 2, 2026 11:41 View session

CopilotAI reviewed Mar 2, 2026
View reviewed changes

vishesh92 force-pushed the feature-kms branch 2 times, most recently from 75519c2 to 1fce0b2Compare March 4, 2026 06:38

apache deleted a comment from blueorangutan Mar 5, 2026

vishesh92 requested a review from sureshanaparti March 5, 2026 12:23

vishesh92 added 2 commits June 9, 2026 19:54

fixup
e09f356

Make HSM Profile domain scoped
be372b7

github-actionsBot mentioned this pull request Jun 9, 2026
[repo-status] Daily Status Report – June 9, 2026 #13386
Closed

fixup
7410669

kiranchavala approved these changes Jun 12, 2026
View reviewed changes

github-actionsBot mentioned this pull request Jun 12, 2026
[repo-status] Daily Status Report — June 12, 2026 #13413
Closed

CopilotAI reviewed Jun 23, 2026

harikrishna-patnala approved these changes Jun 30, 2026
View reviewed changes

winterhazel mentioned this pull request Jul 2, 2026
Add KMSWrappedKeyDao as a dependency for the Usage server #13535
Merged
10 tasks

Uh oh!

Conversation

vishesh92 commented Feb 26, 2026• edited by sureshanaparti Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Management Service (KMS) with HSM Integration

Description

New APIs

New Database Tables

New Global Settings

UI Changes

How to Test

Uh oh!

codecovBot commented Feb 26, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

blueorangutan commented Feb 26, 2026

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vishesh92 commented Mar 4, 2026

Uh oh!

blueorangutan commented Mar 4, 2026

Uh oh!

blueorangutan commented Mar 4, 2026

Uh oh!

vishesh92 commented Mar 5, 2026

Uh oh!

blueorangutan commented Mar 5, 2026

Uh oh!

blueorangutan commented Mar 5, 2026

Uh oh!

vishesh92 commented Jun 8, 2026

Uh oh!

blueorangutan commented Jun 8, 2026

Uh oh!

blueorangutan commented Jun 8, 2026

Uh oh!

vishesh92 commented Jun 8, 2026

Uh oh!

blueorangutan commented Jun 8, 2026

Uh oh!

blueorangutan commented Jun 9, 2026

Uh oh!

vishesh92 commented Jun 9, 2026

Uh oh!

blueorangutan commented Jun 9, 2026

Uh oh!

blueorangutan commented Jun 9, 2026

Uh oh!

vishesh92 commented Jun 10, 2026

Uh oh!

blueorangutan commented Jun 10, 2026

Uh oh!

blueorangutan commented Jun 10, 2026

Uh oh!

kiranchavala left a comment

Choose a reason for hiding this comment

Uh oh!

weizhouapache commented Jun 23, 2026

Uh oh!

weizhouapache commented Jun 23, 2026

Uh oh!

blueorangutan commented Jun 23, 2026

Uh oh!

vishesh92 commented Feb 26, 2026•
edited by sureshanaparti
Loading

codecovBot commented Feb 26, 2026•
edited
Loading