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 17.88800% with 2566 lines in your changes missing coverage. Please review.
✅ Project coverage is 18.03%. Comparing base (e2c13da) to head (33f3d3d).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...java/org/apache/cloudstack/kms/KMSManagerImpl.java	34.63%	646 Missing and 22 partials ⚠️
...udstack/kms/provider/pkcs11/PKCS11HSMProvider.java	12.13%	414 Missing and 6 partials ⚠️
...e/cloudstack/kms/provider/DatabaseKMSProvider.java	0.00%	149 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 ⚠️
...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 ⚠️
...pache/cloudstack/kms/dao/KMSKekVersionDaoImpl.java	0.00%	50 Missing ⚠️
.../api/command/user/kms/hsm/CreateHSMProfileCmd.java	0.00%	49 Missing ⚠️
... and 38 more

Additional details and impacted files

@@             Coverage Diff             @@
##               main   #12711     +/-   ##
===========================================
  Coverage     18.02%   18.03%             
- Complexity    16620    16723    +103     
===========================================
  Files          6029     6064     +35     
  Lines        542181   545705   +3524     
  Branches      66450    66753    +303     
===========================================
+ Hits          97737    98417    +680     
- Misses       433428   436234   +2806     
- Partials      11016    11054     +38

Flag	Coverage Δ
uitests	`3.51% <ø> (-0.02%)`	⬇️
unittests	`19.19% <17.88%> (+<0.01%)`	⬆️

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

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

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

vishesh92 · 2026-04-29T13:49:43Z

@blueorangutan package

blueorangutan · 2026-04-29T13:52:06Z

@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-29T14:05:27Z

Packaging result [SF]: ✖️ el8 ✖️ el9 ✖️ debian ✖️ suse15. SL-JID 17656

vishesh92 · 2026-04-30T05:08:08Z

@blueorangutan package

blueorangutan · 2026-04-30T05: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-04-30T05:51:28Z

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

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

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

sureshanaparti reviewed Apr 28, 2026

View reviewed changes

Comment thread api/src/main/java/org/apache/cloudstack/api/command/user/kms/hsm/CreateHSMProfileCmd.java Outdated

sureshanaparti reviewed Apr 28, 2026

View reviewed changes

Comment thread engine/schema/src/main/java/org/apache/cloudstack/kms/KMSKekVersionVO.java

sureshanaparti reviewed Apr 28, 2026

View reviewed changes

Comment thread server/src/main/java/org/apache/cloudstack/kms/KMSManagerImpl.java Outdated

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

vishesh92 added 2 commits April 29, 2026 13:15

Fix pre-commit error

b9a8f0f

fixup

24771d4

Fix failing unit tests

33f3d3d

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!

blueorangutan commented Apr 16, 2026

Uh oh!

github-actions Bot commented Apr 16, 2026

Uh oh!

blueorangutan commented Apr 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sureshanaparti left a comment

Choose a reason for hiding this comment

Uh oh!

vishesh92 commented Apr 29, 2026

Uh oh!

blueorangutan commented Apr 29, 2026

Uh oh!

blueorangutan commented Apr 29, 2026

Uh oh!

vishesh92 commented Apr 30, 2026

Uh oh!

blueorangutan commented Apr 30, 2026

Uh oh!

blueorangutan commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

vishesh92 commented Feb 26, 2026 •

edited by sureshanaparti

Loading

codecov Bot commented Feb 26, 2026 •

edited

Loading