Fortanix DSM Secure Node Join (on-prem only)

1.0 Introduction

This document describes the Secure Node Join feature in Fortanix-Data-Security-Manager (DSM) and how to add new nodes to an existing cluster.

Secure Node Join is a security feature that controls which hardware nodes can join a Fortanix DSM cluster. When Secure Node Join is enabled, a node must present a verifiable hardware identity derived from its CPU Platform Provisioning ID (PPID). Fortanix DSM verifies this identity against the cluster's AllowList before permitting the node to join. This ensures that only trusted, verified hardware can become part of the cluster.

Fortanix DSM supports two node join workflows depending on whether a Quorum approval policy is configured:

Without Quorum approval: A single system administrator (sysadmin) approves the node join request from the TRUST CENTER.
With Quorum approval: A minimum number of system administrators must approve the node join request from the Tasks → PENDING tab before the node is permitted to join.

NOTE
This feature is available for on-premises deployments only, with DCAP attestation enabled.

2.0 Prerequisites

Ensure the following:

Fortanix DSM on-premises cluster with Secure Node Join enabled. It is configured in the deployment YAML file at cluster creation time. For more information, refer to Fortanix DSM Installation Guide - On-Premises.
DCAP attestation enabled on the cluster (onlineWithTrustedNodeIdentity or offlineWithTrustedNodeIdentity).
A user with system administrator credentials to log in to the cluster.
For Quorum approval: The required minimum number of system administration users configured as Quorum approvers before any node join is attempted. For more information, refer to Sysadmin Settings - Quorum Policy.

3.0 Node Identity

When a node attempts to join a cluster with Secure Node Join enabled, it presents a hardware identity derived from its DCAP attestation report. The node's PPID is extracted from its DCAP attestation report, and a SHA-256 hash of this value is base64 encoded to produce the final node identity.

The node identity is visible in:

The TRUST CENTER tab under System Administration → Cluster.
The sdkms pod logs of existing cluster nodes.

For example, in the sdkms pod log of an existing cluster node, you can see the following log:

2024-10-21 13:11:33.505Z INFO backend::api::cluster - new node_identity added: ABcajcYepnCqhMnz7yYXndghKFeESvqqujecavX2FVg=

4.0 Trust Center

The TRUST CENTER tab displays all node identities for nodes that have joined the cluster or have a pending join request.

Navigate to System Administration → Cluster → TRUST CENTER tab.

The table contains the following columns:

NODE IDENTITY: The base64-encoded SHA-256 hash of the node's hardware PPID.
TRUST STATUS: The current status of the node. Possible values are:
- Pending: The node has requested to join and is awaiting approval.
- Trusted: The node has been approved and is permitted to join the cluster.
- Rejected: The node join request has been declined.
You can filter the nodes by status, such as Pending, Trusted, and Rejected.
APPROVER: Indicates the approver for the node join request.

NOTE
System operators can view node identity requests in the TRUST CENTER tab but are not authorized to approve or decline the requests.

5.0 Create a Cluster with Secure Node Join

To enable Secure Node Join, configure the deployment YAML file (config.yaml) before creating the cluster as described in Fortanix DSM Installation Guide - On-Premises.

For DCAP online attestation with Secure Node Join enabled, add the following parameters under the global section:

global:
  attestation:
    dcap:
      type: onlineWithTrustedNodeIdentity

For DCAP offline attestation with Secure Node Join enabled, add the following parameters under the global section:

global:
  attestation:
    dcap:
      type: offlineWithTrustedNodeIdentity

Once configured, the Secure Node Join enrollment policy is visible under System Administration → Settings → ENROLLMENT POLICY tab.

**Figure 2: Trusted node identity check box**

6.0 Secure Node Join Without Quorum Approval

This section describes the node join flow when no Quorum approval policy for Secure Node Join is configured in the System Administration account.

6.1 Run the Join Command

On the new node, run the following command to join the cluster:

If the nodes are in the same subnet:

sudo sdkms-cluster join --peer=<existing node IP>/<subnet-mask> --token=<token>

If the nodes are in a different subnet:

sudo sdkms-cluster join --peer=<existing node IP> --token=<kubeadm-token> --self=<node IP address>

The join command will not complete immediately. The node's identity is recorded as PENDING in the TRUST CENTER.

6.2 Approve or Decline the Node Join Request

Perform the following steps to review and accept or reject the node join request:

Log in to the Fortanix DSM cluster using your system administrator credentials.
Navigate to System Administration → Cluster → TRUST CENTER tab.
Locate the pending node entry and note the NODE IDENTITY value. Verify it against the sdkms pod logs of an existing cluster node to confirm it matches the expected node.
Click APPROVE to approve the node join request or DECLINE to reject it.
If approved, the TRUST STATUS changes to Trusted. If declined, it changes to Rejected.

7.0 Secure Node Join With Quorum Approval

This section describes the node join flow when a Quorum approval policy for Secure Node Join is configured in the System Administration account. In this flow, a minimum number of system administrator(s) must approve the join request before the node is permitted to join.

A Quorum approver is a system administrator designated to review and approve Secure Node Join requests.

7.1 Configure the Quorum Approval Policy

After the cluster is created, configure the Quorum approval policy for Secure Node Join, if not already configured. Navigate to System Administration → Settings → QUORUM POLICY tab and configure the policy. For more information, refer to Sysadmin Settings - Quorum Policy.

7.2 Restart the Cluster

After configuring the Quorum approval policy, run the following command to execute the backend rolling restart script:

sudo ./dsm_backend_rolling_restart.sh

This restarts the cluster to apply the updated configurations.

NOTE
A restart is mandatory after any changes to the Quorum approval policy configuration.

7.3 Run the Join Command

On the new node, run the following command to join the cluster:

If the nodes are in the same subnet:

sudo sdkms-cluster join --peer=<existing node IP>/<subnet-mask> --token=<token>

If the nodes are in a different subnet:

sudo sdkms-cluster join --peer=<existing node IP> --token=<kubeadm-token> --self=<node IP address>

The join command will not complete immediately. The node's identity is recorded as PENDING in the TRUST CENTER. When a system administrator approves the request from the TRUST CENTER, a Quorum approval request is automatically generated and sent to all configured Quorum approvers for approval.

7.4 Review the Pending Node Join Request

Perform the following steps to review and accept or reject the node join request:

Log in to the Fortanix DSM cluster using your system administrator credentials.
Navigate to System Administration → Cluster → TRUST CENTER tab.
Locate the pending node entry and note the NODE IDENTITY value.
NOTE
Do not approve a join request for a node identity without independently verifying against the hardware inventory. Approving an unrecognized node identity may allow a rogue node to join the cluster.
Click APPROVE or DECLINE for the pending node entry. When a Quorum approval policy is configured, this action triggers a Quorum approval request that is automatically sent to all designated Quorum approvers in the System Administration account.
After approving the request, the APPROVE and DECLINE buttons are disabled for that the quorum approver, indicating that a Quorum approval request is awaiting review from the remaining Quorum approvers.
Figure 4: Approve node join request
After approving the request, the APPROVE and DECLINE buttons are disabled for that the quorum approver, indicating that a Quorum approval request is awaiting review from the remaining Quorum approvers.
The Quorum approval request appears in the Tasks → PENDING tab for each Quorum approver upon log in. Each Quorum approver must review and approve or decline the request from the Tasks → PENDING tab.

7.5 Approve or Decline Quorum Approval Request

Perform the following steps to accept or reject the node join request

Navigate to System Administration → Tasks → PENDING tab.
Locate the pending Quorum approval request for the node join. The request details display the node identity in the following format:
```
operation: /admin/v1/cluster/node_identities/<node_identity_hash>
   method: PATCH
   body: {"status":"TRUSTED"}
```
Click APPROVE to approve the request or DECLINE to reject the request.
Figure 5: Approve in tasks tab
On the Quorum approval request confirmation dialog box, review the request details including the requester, request body containing the node identity, and the approval status. Click APPROVE to approve or DECLINE to decline the request.
Once the required number of Quorum approvers approve the request, the node's identity is added to the AllowList and node is successfully joined to the cluster.

NOTE
A single decline from any Quorum approver immediately causes the request to lapse.
The approval request expiration period is configured under System Administration → Settings → POLICIES → Quorum Approval. By default, approval requests expire after 90 days.
Once a Quorum approver approves a request, the APPROVE button is disabled for that user to prevent duplicate approvals.