Skip to main content
Element Software
A newer release of this product is available.

Rekey software encryption at rest master key

Contributors
PDFs

You can use the Element API to rekey an existing key. This process creates a new replacement master key for your external key management server. Master keys are always replaced by new master keys and never duplicated or overwritten.

You might need to rekey as part of one of the following procedures:

  • Create a new key as part of a change from internal key management to external key management.

  • Create a new key as a reaction to or as protection against a security-related event.

Note This process is asynchronous and returns a response before the rekey operation is complete. You can use the GetAsyncResult method to poll the system to see when the process has completed.
What you'll need
Steps

  1. Run the ListKeyProvidersKmip command and copy the key provider ID (keyProviderID).

  2. Run the RekeySoftwareEncryptionAtRestMasterKey with the keyManagementType parameter as external and keyProviderID as the ID number of the key provider from the previous step:

    {
 "method": "rekeysoftwareencryptionatrestmasterkey",
 "params": {
   "keyManagementType": "external",
   "keyProviderID": "<ID number>"
 }
}

  3. Copy the asyncHandle value from the RekeySoftwareEncryptionAtRestMasterKey command response.

  4. Run the GetAsyncResult command with the asyncHandle value from the previous step to confirm the change in configuration. From the command response, you should see that the older master key configuration has been updated with new key information. Copy the new key provider ID for use in a later step.

    {
   "id": null,
   "result": {
     "createTime": "2021-01-01T22:29:18Z",
     "lastUpdateTime": "2021-01-01T22:45:51Z",
     "result": {
       "keyToDecommission": {
         "keyID": "<value>",
         "keyManagementType": "internal"
     },
     "newKey": {
       "keyID": "<value>",
       "keyManagementType": "external",
       "keyProviderID": <value>
     },
     "operation": "Rekeying Master Key. Master Key management being transferred from Internal Key Management to External Key Management with keyProviderID=<value>",
     "state": "Ready"
   },
   "resultType": "RekeySoftwareEncryptionAtRestMasterKey",
   "status": "complete"
}

  5. Run the GetSoftwareEncryptionatRestInfo command to confirm that new key details, including the keyProviderID, have been updated.

    {
   "id": null,
   "result": {
     "masterKeyInfo": {
       "keyCreatedTime": "2021-01-01T22:29:18Z",
       "keyID": "<updated value>",
       "keyManagementType": "external",
       "keyProviderID": <value>
     },
     "rekeyMasterKeyAsyncResultID": <value>
     "status": "enabled",
     "version": 1
   },
}

Find more information