DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
Page History
...
KEK Size vs DEK Size (Important Distinction)
| What | Source | Used For |
|---|---|---|
| KEK size | keybits parameter in createKMSKey / rotateKMSKey (stored in kms_keys.key_bits) | Size of the Key Encryption Key stored in the HSM or database. Used when creating or rotating a KEK. |
| DEK size | Global config kms.dek.size.bits | Size of the Data Encryption Key generated per volume. Used in generateVolumeKeyWithKek(). |
- The KMS key's
keybitscontrols only the KEK size (e.g., 256-bit AES key in the HSM). - The global setting
kms.dek.size.bitscontrols 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.
...
- Authorization: Admin, ResourceAdmin, DomainAdmin, User
- Async: No
Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
name | Yes | String | Name of the KMS key |
description | No | String | Description of the KMS key |
purpose | Yes | String | Purpose of the key (volume, tls) |
zoneid | Yes | UUID | Zone ID where the key will be valid |
hsmprofileid | Yes | UUID | HSM profile ID to create the KEK in |
keybits | No | Integer | KEK size in bits (128, 192, 256). Default: 256 |
account | No | String | Account name (admin use) |
domainid | No | UUID | Domain ID (admin use) |
listKMSKeys
Lists KMS keys available to the caller.
- Authorization: Admin, ResourceAdmin, DomainAdmin, User
Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
id | No | UUID | List KMS key by UUID |
purpose | No | String | Filter by purpose |
zoneid | No | UUID | Filter by zone |
state | No | String | Filter by state (Enabled, Disabled) |
updateKMSKey
Updates KMS key name, description, or state.
- Authorization: Admin, ResourceAdmin, DomainAdmin, User
- Async: Yes
Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
id | Yes | UUID | KMS key UUID |
name | No | String | New name |
description | No | String | New description |
enabled | No | Boolean | Enable/disable the key |
deleteKMSKey
Deletes a KMS key (only if not referenced by volumes or wrapped keys).
- Authorization: Admin, ResourceAdmin, DomainAdmin, User
- Async: Yes
Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
id | Yes | UUID | KMS key UUID |
rotateKMSKey
Rotates KEK by creating a new version and scheduling gradual re-encryption of wrapped keys.
- Authorization: Admin only
- Async: Yes
Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
id | Yes | UUID | KMS key UUID to rotate |
keybits | No | Integer | Key size for new KEK (default: same as current) |
hsmprofileid | No | UUID | Target HSM profile for cross-HSM migration |
migrateVolumesToKMS
Migrates passphrase-based volumes to KMS encryption.
- Authorization: Admin only
- Async: Yes
Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
zoneid | Yes | UUID | Zone ID |
id | Yes | UUID | KMS key ID to migrate volumes to |
account | No | String | Migrate volumes for specific account |
domainid | No | UUID | Domain ID |
HSM Profile APIs
addHSMProfile
...
- Authorization: Admin only
- Request has sensitive info: Yes (PIN, passwords)
Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
name | Yes | String | HSM profile name |
protocol | No | String | Protocol (PKCS11, KMIP, etc.). Default: pkcs11 |
zoneid | No | UUID | Zone ID (null = global scope) |
domainid | No | UUID | Domain ID |
account | No | String | Account name |
system | No | Boolean | System profile (globally available, root admin only) |
vendorname | No | String | HSM vendor name |
details | No | Map | HSM configuration details |
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:
| Parameter | Required | Type | Description |
|---|---|---|---|
id | No | UUID | HSM profile ID |
zoneid | No | UUID | Zone ID |
protocol | No | String | Protocol filter |
enabled | No | Boolean | Enabled filter |
updateHSMProfile
Updates an HSM profile name or enabled state.
- Authorization: Admin only
Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
id | Yes | UUID | HSM profile UUID |
name | No | String | New name |
enabled | No | Boolean | Enable/disable |
deleteHSMProfile
Deletes an HSM profile (only if not in use by any KEK versions).
- Authorization: Admin only
Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
id | Yes | UUID | HSM profile UUID |
Global Settings
| Setting Key | Scope | Type | Default | Description |
|---|---|---|---|---|
kms.dek.size.bits | Global | Integer | 256 | Size of DEKs in bits for new volumes (128, 192, 256) |
kms.retry.count | Global | Integer | 3 | Number of retry attempts for transient KMS failures |
kms.retry.delay.ms | Global | Integer | 1000 | Delay in milliseconds between retry attempts |
kms.operation.timeout.sec | Global | Integer | 30 | Per-attempt timeout for KMS operations |
kms.rewrap.batch.size | Global | Integer | 50 | Wrapped keys rewrapped per batch in background job |
kms.rewrap.interval.ms | Global | Long | 300000 | Interval between background rewrap executions (5 min) |
Database Changes
New Tables
...
| Code Block |
|---|
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; |
...
Overview
Content Tools