CDK Protection Using DKS

1.0 Introduction

The purpose of this article is to describe the process to protect the Cluster Master Key (CMK) wrapping key using another key, the Deployment Key Store (DKS), which is stored in an external HSM when Fortanix-Data-Security-Manager (DSM) is deployed on non-SGX platforms such as Amazon Web Services (AWS).

2.0 Architecture

Fortanix DSM generates a CMK during cluster creation. All data stored in the Fortanix DSM database is protected by keys derived from the CMK. When a node joins the cluster, it receives a copy of the CMK from its peers and then wraps it with the Platform Key before writing it to the database.

For SGX platforms, the Platform Key is derived from hardware-bound keys built into the CPU, such as the SGX sealing key and attestation key.  

For non-SGX (software-mode) platforms, the CMK is generated locally using a Cluster Key created by Fortanix DSM during cluster initialization. The CMK is then protected at rest using a Platform Key (CMK Wrapping Key) derived from the contents of the Deployment Key Store (DKS) mapped using a CPU SVN, along with machine identity and application identity (DSM version).

The DKS maintains deployment keys on a per-SVN basis. Each deployment key may either:

• Contain locally generated key material, or

• Reference a key generated and stored in an external HSM (such as a Fortanix DSM cluster or a PKCS#11 HSM connected through the HSM Gateway).

When an external HSM is configured, it strengthens the protection of the Deployment Key, which in turn strengthens the derived Platform Key used to wrap the CMK. The CMK derivation process itself remains local and unchanged, regardless of DKS configuration.

During CMK rotation, new deployment keys (local or external, depending on configuration) may be generated, and new Platform Keys are derived accordingly to continue protecting the CMK at rest.

If an external HSM is configured, its connection details (such as URL, slot, credentials, or API key) are stored within the DKS Kubernetes secret.

3.0 Configuration Format

The configuration format is a YAML file with the following fields:

• kind: (required) Enter either "Fortanix", "Ncipher", or "Safenet".

• url: (required) The hostname or IP address, and optionally port, of the Fortanix DSM cluster or Fortanix HSM Gateway to connect to, separated by a colon, for example, <fortanix_dsm_url> or hsm-gateway.example.com:4442.

  NOTE

  This is not a full URL as per RFC 3986, therefore, https:// <fortanix_dsm_url> is not valid, but <fortanix_dsm_url> is.

• pin: (required)

  • For Fortanix DSM clusters: the API key of the app to use to export the external Deployment Key.

  • For PKCS#11 HSMs: the PIN to log into the HSM.

• slot: (required for PKCS#11 HSMs only) The slot of the token with the external Deployment Key.

• tls: (required) A JSON object describing the TLS configuration. It has the following fields:

  • mode: (required) Either "required" or "opportunistic". Using "opportunistic" disables many security checks, so only "required" should be used in production. The other fields are only available in "required" mode.

  • validate_hostname: (required) Either true or false. Only true should be used in production.

  • ca: (required) A JSON object describing the trusted certificate authorities to use. Must contain exactly one of the following fields:

    • ca_set: Must be set to "global_roots". This uses the node’s built-in set of root CA’s.

    • pinned: A list of strings, each of which is a base64-encoded PEM certificate. That is, the entire PEM certificate, guards included, is run through base64 encoding.

      This can be produced with the following Unix command:

      base64 -w0 < my_ca_cert.pem

  • client_cert: (optional): A client certificate to use for mutual authentication. This is a base-64 encoded PEM certificate. See above for encoding.

  • client_key: (optional): A client private key to use for mutual authentication. This is a base-64 encoded PEM key. See above for encoding.

• extKeyId: (required): The unique identifier of the external Deployment Key in the configured HSM. This key is used by the Deployment Key Store (DKS) to derive Platform Keys (including the CMK Wrapping Key). The identifier must correspond to an AES-256 key generated and stored in the external HSM.

3.1 Example

To store the CDK in the Fortanix DSM cluster at <fortanix_dsm_url>, the config should appear as follows:

cat ext_hsm.yaml 
extHsm:
   kind: "Fortanix"
   url: "sit.smartkey.io"
   tls:
     mode: "required"
     validate_hostname: true
     ca:
       ca_set: "global_roots"
   pin: "ODNiYmFlMTct...SDlB"
extKeyId:
   id: 157cd33d-1006-4843-9f66-e0bc45857939

Similarly, to store the DK in slot 1 of an nCipher PKCS#11 HSM using the HSM Gateway at hsm-gateway.example.com, the config should appear as follows:

cat ext_hsm.yaml 
extHsm:
   kind: "Ncipher"
   url: "hsm-gateway.example.com"
   tls:
     mode: "required"
     validate_hostname: true
     ca:
       ca_set: "global_roots"
   slot: 1
   pin: "<HSM pin here>"
extKeyId:
   id: 157cd33d-1006-4843-9f66-e0bc45857939

4.0 Creating a New Cluster

Perform the following steps to create a new cluster:

1. Create the Fortanix DSM cluster by running the following command:

   sdkms-cluster create --self=<server ip address/subnet mask> --config ./config.yaml

2. Run get_csrs.

3. You will be prompted for the JSON configuration described in Section 3.1: Example. Paste it here, followed by a blank line.

5.0 Migrating an Existing Cluster or Changing Configuration (Non-SGX) - DSM 5.6 and Above

For migration steps, refer to the Fortanix Data Security Manager CDK to DKS Migration guide.