Page History

Project Introduction

This document outlines the design for a comprehensive Key Management Service (KMS) in Apache CloudStack that provides envelope encryption for volume encryption using Hardware Security Modules (HSMs) or a database-backed fallback provider (also used for testing).

...

KEK Size vs DEK Size (Important Distinction)

• The KMS key's keybits controls only the KEK size (e.g., 256-bit AES key in the HSM).
• The global setting kms.dek.size.bits controls the DEK size for all new encrypted volumes.
• DEK size is independent of the KMS key; all volumes get DEKs of the configured global size.

...

• HSM Profile Management (Admin only)

  • Add HSM Profile: Configure connection to HSM devices (PKCS#11-compliant)
  • Profile Scoping: User-owned, zone-level, or global (systempublic) profiles
  • Profile Validation: Health check on configured HSM connections
  • Sensitive data encryption: PINs and passwords are encrypted via DBEncryptionUtil before storage

• KMS Key Management

  • Key Creation: Create KMS keys (KEKs) bound to an HSM profile, zone, and account
  • Key Update: Enable/disable keys, update name and description
  • Key Deletion: Soft-delete keys (only if not in use by volumes or wrapped keys)
  • Key Listing: List keys with filtering by purpose, zone, state, and account

• Key Rotation

  • Same-HSM Rotation: Create a new KEK version in the same HSM with a new label
  • Cross-HSM Migration: Create a new KEK version in a different HSM profile
  • Transaction Atomicity: Database updates for new KEK version and key profile are wrapped in a Transaction.execute() block; orphaned HSM keys are cleaned up on DB failure
  • Background Rewrap: Gradual re-encryption of wrapped keys in configurable batches

• Volume Encryption Integration

  • DEK Generation: Generate random DEKs (configurable size via kms.dek.size.bits) and wrap them with the active KEK version
  • DEK Unwrapping: Unwrap DEKs on demand for volume access (plaintext DEKs are zeroized after use)
  • Volume Migration: Migrate legacy passphrase-encrypted volumes to KMS encryption

• Plugin Architecture

  • DatabaseKMSProvider: Database-backed KEK storage with AES/GCM/NoPadding encryption via DBEncryptionUtil
  • PKCS11HSMProvider: PKCS#11 HSM integration with per-profile session pooling and AES/CBC/PKCS5Padding wrapping

• Concurrency & Cluster Safety

  • Bounded thread pool for KMS operations: ThreadPoolExecutor(core=2, max=100, keepAlive=60s, SynchronousQueue) with daemon threads
  • Cluster-aware rewrap: GlobalLock("kms.rewrap.worker") prevents duplicate rewrap work across management server nodes
  • ScheduledExecutorService (replaces java.util.Timer) for robust periodic rewrap scheduling

...

1. User-Owned Profile: account_id set → visible only to that account
2. Zone Admin Profile: zone_id set, account_id NULL → visible to all accounts in that zone
3. Global Admin Profile: zone_id NULL, account_id NULL, system is_public = TRUE → visible to all accounts in all zones

...

• Authorization: Admin, ResourceAdmin, DomainAdmin, User
• Async: No

Parameters:

listKMSKeys

Lists KMS keys available to the caller.

• Authorization: Admin, ResourceAdmin, DomainAdmin, User

Parameters:

updateKMSKey

Updates KMS key name, description, or state.

• Authorization: Admin, ResourceAdmin, DomainAdmin, User
• Async: Yes

Parameters:

deleteKMSKey

Deletes a KMS key (only if not referenced by volumes or wrapped keys).

• Authorization: Admin, ResourceAdmin, DomainAdmin, User
• Async: Yes

Parameters:

rotateKMSKey

Rotates KEK by creating a new version and scheduling gradual re-encryption of wrapped keys.

• Authorization: Admin only
• Async: Yes

Parameters:

migrateVolumesToKMS

Migrates passphrase-based volumes to KMS encryption.

• Authorization: Admin only
• Async: Yes

Parameters:

HSM Profile APIs

addHSMProfile

...

• Authorization: Admin only
• Request has sensitive info: Yes (PIN, passwords)

Parameters:

PKCS#11 details keys: library (path to PKCS#11 library), slot (slot number), pin (HSM PIN, encrypted at rest), token_label (token label), minSessions, maxSessions

...

• Authorization: Admin, ResourceAdmin, DomainAdmin, User
• Response has sensitive info: Yes (encrypted values shown as ENC(...))

Parameters:

updateHSMProfile

Updates an HSM profile name or enabled state.

• Authorization: Admin only

Parameters:

deleteHSMProfile

Deletes an HSM profile (only if not in use by any KEK versions).

• Authorization: Admin only

Parameters:

Global Settings

Database Changes

New Tables

...

CREATE TABLE IF NOT EXISTS `cloud`.`kms_hsm_profiles` (
    `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    `uuid` VARCHAR(40) NOT NULL,
    `name` VARCHAR(255) NOT NULL,
    `protocol` VARCHAR(32) NOT NULL COMMENT 'PKCS11, KMIP, AWS_KMS, etc.',
    `account_id` BIGINT UNSIGNED COMMENT 'null = admin-provided',
    `domain_id` BIGINT UNSIGNED,
    `zone_id` BIGINT UNSIGNED COMMENT 'null = global scope',
    `vendor_name` VARCHAR(64),
    `enabled` BOOLEAN NOT NULL DEFAULT TRUE,
    `system``is_public` BOOLEAN NOT NULL DEFAULT FALSE,
    `created` DATETIME NOT NULL,
    `removed` DATETIME,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_uuid` (`uuid`),
    UNIQUE KEY `uk_account_name` (`account_id`, `name`, `removed`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

...