Edit KEK Parameters

The ability to edit KEK parameters depends on the setting of the expiration_options parameter for the KEK. This parameter can be:

  • no_change — The KEK expiration options cannot be changed after the Cloud VM Set has been created. Once the top-level key expires it cannot be reactivated and all VMs will be automatically detached from KeyControl when the expiration date is reached.
  • change — The KEK expiration options can be changed after the Cloud VM Set has been created, but the kek_expire_days option cannot be extended beyond the original date.
  • extend — All KEK expiration options can be changed after the Cloud VM Set has been created.

Request

Method

URI

PATCH

 
v5/kek_edit/

Privileges Required

Any valid KeyControl user account with CLOUD_ADMIN privileges can edit the KEK parameters for a Cloud VM Set as long as that user account is a member of the Cloud Admin Group associated with the Cloud VM Set.

Parameters

Name

Type

Example

cvmset_guid

string

 
30dd18df-185f-11e8-a8fd-000c2997200a

The GUID for the Cloud VM Set. The GUID is returned when the Cloud VM Set is created and when you view the details of a Cloud VM Set.

kek_expire_days

integer

1209600

The number of seconds for which the KEK is valid. The default is 1209600 seconds (14 days). To indicate that the KEK should never expire, specify 0 (zero).

When this time period expires:

  • All disks on all VMs in the Cloud VM Set are automatically detached. What happens to the keys depends on the setting in the Key Expiration Action field.
  • Any attempt to register a new VM with the Cloud VM Set will fail.
  • Any encrypt or decrypt operation on any of the associated VMs will fail.
kek_expire_action string

NO USE

The action to be taken when the KEK expires. Allowable values:

  • NO USE — The KEK and all data encryption keys are deactivated but retained. The keys can be reactivated and the expiration date extended if the Key Expiration Option field is set to Extend. This is the default.

  • SHRED — The KEK and all data encryption keys are destroyed and cannot be retrieved. In addition, all VMs in the set are removed from KeyControl and the Cloud VM Set itself is deleted.

expiration_options

string

extend

Allowable Values:

  • no_change — The KEK expiration options cannot be changed after the Cloud VM Set has been created. This is the default. Selecting this option means that once the top-level key expires it cannot be reactivated and all VMs will be automatically detached from KeyControl when the expiration date is reached.
  • change — The KEK expiration options can be changed after the Cloud VM Set has been created, but the kek_expire_days option cannot be extended beyond the original date.
  • extend — All KEK expiration options can be changed after the Cloud VM Set has been created.

retention_period

integer

 
7776000

If kek_expire_action is set to NO USE, this field determines the number of seconds for which Cloud VM Set objects will be retained after the expiration date is reached. The default is 7,776,000 second (90 days).

After this period passes, KeyControl permanently deletes the Cloud VM Set, all VMs registered with that set, and the associated KEK.

Response

Name

Type

Example

result

string

 
success

Errors

Reason

Example

Invalid Cloud VM Set GUID

 
Cloud VM Set not found