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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 3.51%. Comparing base (e2c13da) to head (436d0bf).

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

HEAD has 1 upload less than BASE

Flag BASE (e2c13da) HEAD (436d0bf)

unittests 1 0

Additional details and impacted files

@@              Coverage Diff              @@
##               main   #12711       +/-   ##
=============================================
- Coverage     18.02%    3.51%   -14.52%     
=============================================
  Files          6029      465     -5564     
  Lines        542181    40311   -501870     
  Branches      66450     7597    -58853     
=============================================
- Hits          97737     1415    -96322     
+ Misses       433428    38706   -394722     
+ Partials      11016      190    -10826

Flag	Coverage Δ
uitests	`3.51% <ø> (-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.

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

github-actions · 2026-04-14T17:32:19Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

vishesh92 · 2026-04-16T06:59:10Z

@blueorangutan package

blueorangutan · 2026-04-16T07: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-04-16T08:00:37Z

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

vishesh92 · 2026-04-16T08:04:40Z

@blueorangutan test keepEnv

blueorangutan · 2026-04-16T08:06:04Z

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

github-actions · 2026-04-16T23:31:50Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

blueorangutan · 2026-04-16T23:42:54Z

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

Test	Result	Time (s)	Test File
test_01_add_hsm_profile_admin	`Error`	13.35	test_kms_lifecycle.py
test_02_list_hsm_profiles	`Error`	11.68	test_kms_lifecycle.py
test_03_update_hsm_profile	`Error`	12.47	test_kms_lifecycle.py
test_09_delete_kms_key	`Error`	9.47	test_kms_lifecycle.py
test_11_delete_hsm_profile_with_keys_negative	`Error`	11.94	test_kms_lifecycle.py
test_13_delete_hsm_profile	`Error`	13.27	test_kms_lifecycle.py

sureshanaparti · 2026-04-28T07:34:23Z

+    }
+
+    public Map<String, String> getDetails() {
+        Map<String, String> detailsMap = new HashMap<>();


Suggested change

Map<String, String> detailsMap = new HashMap<>();

return convertDetailsToMap(details);

use the common method

sureshanaparti · 2026-04-28T07:48:01Z

+    private Date created;
+    @Column(name = GenericDao.REMOVED_COLUMN)
+    @Temporal(TemporalType.TIMESTAMP)
+    private Date removed;


@vishesh92 can maintain spacing between column parameters same as other VOs.

sureshanaparti · 2026-04-28T08:16:25Z

+    private static final Logger logger = LogManager.getLogger(KMSManagerImpl.class);
+    private static final Map<String, KMSProvider> kmsProviderMap = new HashMap<>();
+    private final ExecutorService kmsOperationExecutor = new ThreadPoolExecutor(
+            2, 100, 60L, TimeUnit.SECONDS, new SynchronousQueue<>(), r -> {


any of these needs a config?

sureshanaparti

@vishesh92 minor comments, check/address them and resolve conflicts. overall clgtm.

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

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

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

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

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

Copilot AI 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 943f19a Compare 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 df2df4b Compare March 2, 2026 10:36

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

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

Copilot AI reviewed Mar 2, 2026

View reviewed changes

vishesh92 force-pushed the feature-kms branch 2 times, most recently from 75519c2 to 1fce0b2 Compare 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 3 commits April 14, 2026 23:04

Address comments

4739834

Merge branch 'main' into feature-kms

61aa7ed

fix failing tests

520da69

github-actions Bot removed the status:has-conflicts label Apr 15, 2026

github-actions Bot added the status:has-conflicts label Apr 16, 2026

sureshanaparti reviewed Apr 28, 2026

View reviewed changes

sureshanaparti approved these changes Apr 28, 2026

View reviewed changes

vishesh92 added 2 commits April 28, 2026 16:27

Address comments

b58c46c

Merge branch 'main' into feature-kms

436d0bf

boring-cyborg Bot added component:compute component:integration-test component:kubernetes component:marvin component:networking component:orchestration component:primary-storage component:storage component:UI Python Warning... Python code Ahead! labels Apr 28, 2026

github-actions Bot removed the status:has-conflicts label Apr 28, 2026

	Map<String, String> detailsMap = new HashMap<>();
	return convertDetailsToMap(details);

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!

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

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

blueorangutan commented Feb 26, 2026

Uh oh!

Copilot AI 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!

github-actions Bot commented Apr 14, 2026

Uh oh!

vishesh92 commented Apr 16, 2026

Uh oh!

blueorangutan commented Apr 16, 2026

Uh oh!

blueorangutan commented Apr 16, 2026

Uh oh!

vishesh92 commented Apr 16, 2026

Uh oh!

blueorangutan commented Apr 16, 2026

Uh oh!

github-actions Bot commented Apr 16, 2026

Uh oh!

blueorangutan commented Apr 16, 2026

Uh oh!

sureshanaparti Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

sureshanaparti Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

sureshanaparti Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

sureshanaparti left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

vishesh92 commented Feb 26, 2026 •

edited by sureshanaparti

Loading

codecov Bot commented Feb 26, 2026 •

edited

Loading