CDK to DKS Migration

1.0 Introduction

The purpose of this article is to describe the procedure for migrating an existing Fortanix-Data-Security-Manager (DSM) cluster running in software mode (non-SGX) from the legacy external Cluster Deployment Key (CDK)–based protection model to the new Deployment Key Store (DKS)–based CMK wrapping protection model, or for modifying the DKS configuration of an existing cluster.

This migration ensures that external HSM–backed protection, when configured, continues to protect the Cluster Master Key (CMK) at rest while simplifying CMK derivation and removing the dependency on external CDK-based key generation.

2.0 Migration Steps

The following sections describe an upgrade and migration scenario for a software-mode (non-SGX), CDK-based single-node cluster transitioning to the latest DSM version using external DKS-based CMK wrapping protection.

2.1 Upgrade and Node Initialization

Upgrade the Fortanix DSM cluster to a version that supports external DKS configuration (5.6 or above).

For more information on the steps to upgrade the DSM cluster using the DSM user interface (UI), refer to the Fortanix Data Security Manager Software Upgrade guide.

After upgrade:

The existing CMK remains active until explicitly rotated.
cluster_key_protection will still show "external" until rotation.
The node will have a new node_id after the deploy pod completes.
The DKS is created using the Kubernetes secret sdkms-deployment-key-store.

2.2 Configure External HSM in DKS

This section configures the DKS to use the deployment keys generated and stored in an external HSM. Once configured, the DKS will source the deployment key’s key material from the external HSM instead of using locally generated deployment keys.

Prepare the external HSM configuration file, ext_hsm.yaml:

extHsm:
  kind: "Fortanix"
  url: "sit.smartkey.io"
  tls:
    mode: "required"
    validate_hostname: true
    ca:
      ca_set: "global_roots"
  pin: "<API key or HSM PIN>"
extKeyId:
  id: 157cd33d-1006-4843-9f66-e0bc45857939

Where,

extHsm defines the external HSM configuration.
extKeyId.id is the identifier of the external deployment key to be used by the DKS for CMK wrapping key derivation.

Run the following command to patch the Kubernetes secret sdkms-deployment-key-store with the configuration provided in the above YAML file.
```
sudo sdkms-cluster rotate-dk --ext-hsm ext_hsm.yaml
```
This updates the Kubernetes secret to the following:
- Adds the external key reference into key_map.
- Stores the hmg_config.
- Adds the migration_svn.

Verify using the following command:

sudo kubectl get secret sdkms-deployment-key-store -o jsonpath='{.data}'
{"deployment_key_store":" eyJsYXRlc3... CQVFFQkFRPT0ifQ=="}
$ echo '<above_value>' | base64 -d
{"latest_svn":"AAAAAAAAAAAAAAAAAAAAAA==",
 "key_map":{"AAAAAAAAAAAAAAAAAAAAAA==":"MWBQpg3FH9HRyvMPlmoIUQ==",
            "AQEBAQEBAQEBAQEBAQEBAQ==":{"key_id":
            {"id":"157cd33d-1006-4843-9f66-e0bc45857939"}}},
 "hmg_config":{"kind":"Fortanix","url":"sit.smartkey.io","tls":{"mode":"required","validate_hostname":true,"ca":{"ca_set":"global_roots"},"client_key":null,"client_cert":null},"pin":"ODNiYmFlMTct...SDlB"},
"migration_svn":"AQEBAQEBAQEBAQEBAQEBAQ=="}

Run the following command to navigate to the /bin directory and perform a rolling restart to load the updated DKS configuration:
```
cd /opt/fortanix/sdkms/bin
sudo ./dsm_backend_rolling_restart.sh
```
Once the restart is completed, the pod logs show that the latest sdkms-deployment-key-store configuration is picked up.

2.3 Rotate the CMK

This step describes the process of rotating the CMK, through which a new CMK is generated and wrapped using a fresh Platform Key derived from the newly configured external DKS. The CMK derivation itself changes from external to local; however, its at-rest protection mechanism (the corresponding CMK Wrapping Key) is updated to use deployment keys residing in an external HSM.

NOTE
The CMK Wrapping Key is a type of Platform Key.

CMK rotation is required to complete the migration, as existing CMKs remain active using the protection from the previous configuration until explicitly rotated.

Run the following command to perform the CMK rotation by invoking the propose key API:
```
curl -k https://<pod-ip>:4444/cluster/v1/key/propose -X POST
```
Verify that the key_id has been fetched once using the Activity Logs in the detailed view of the Deployment Key in the Fortanix DSM UI.
Figure 2: Deployment key activity log
This shows that the external Deployment Key was fetched using the hmg_config to derive the CMK wrapping_key.

Run the following command to verify the proposed hash:

curl -k https://<pod-IP>/cluster/v1/key
{"cluster_key_version":1,"cluster_proposal_hash":"gJmhkQZvMEkn5VbyzBUSB9bcW61MhVlkBaiRjFuC/XA=","fetched_proposal_hash":"gJmhkQZvMEkn5VbyzBUSB9bcW61MhVlkBaiRjFuC/XA="}

NOTE
The cluster_key_version is still 1 which means that the existing old CMK is still applicable.

Run the following command to activate the new CMK:

curl -k https://<pod-ip>:4444/cluster/v1/key/activate -X POST

Run the following command to navigate to the /bin directory and execute the script for the backend rolling cluster to allow the cluster to use the new CMK:
```
cd /opt/fortanix/sdkms/bin
sudo ./dsm_backend_rolling_restart.sh
```

2.4 Verify Migration

This section verifies that the migration has completed successfully. Successful verification ensures that the cluster is no longer operating under the legacy external CDK-based protection model and that CMK protection at rest is now backed by the configured external HSM.

Run the following command to verify the new CMK version:
```
curl -k https://<node-ip>:4444/cluster/v1/key
```
You will see the cluster_key_version is updated to 2:
```
{"cluster_key_version":2}
```
Run the following command to verify the cluster_key_protection value for the new CMK. It must update to local after successful migration from external CDK to external DKS mechanism:
```
curl -ks https://<node-ip>:4444/admin/v1/cluster | jq ".cluster_key_protection"
```
Expected:
```
"local"
```
Verify that the key_id has been fetched for the second time using the Activity Logs in the detailed view of the Deployment Key in the Fortanix DSM UI.

The cluster’s CMK is successfully rotated post upgrade to DSM 5.5 version, without turning off the external HSM protection. This indicates that CMK is now locally generated and the CMK wrapping key protection is provided through DKS mechanism.

Documentation Index