Home Knowledge Base SecureW2 Documentation TPM Key Attestation Configuration and Enrollment (Linux) – Integration Guide

TPM Key Attestation Configuration and Enrollment (Linux) – Integration Guide

Introduction

SecureW2 TPM-based key attestation can be integrated with the certificate enrollment workflow to ensure that private keys are securely generated, stored, and validated within trusted hardware.

When an IoT device submits a Certificate Signing Request (CSR), the server cannot determine whether the private key is hardware-protected or software-generated. A TPM attestation validation server ensures that (1) the key is hardware-bound and non-exportable, and (2) the TPM is genuine and vendor-trusted. This guarantees that the issued certificate is cryptographically bound to a specific physical device and cannot be used without its TPM.

The following guide provides step-by-step instructions on setting up TPM Key Attestation for certificate enrollment.

Prerequisites

The following are the prerequisites for setting up TPM key attestation with Linux:

  1. Access to JoinNow Management Portal with Ultimate or Absolute subscription for GBB or Enterprise Enrollment and Attestation (EEA) subscription for Legacy.
  2. TPM 2.0 is available and enabled on the Linux machine.

Configuring JoinNow

The following are the high-level steps to be configured in JoinNow:

  1. Creating an Intermediate CA
  2. Configure Key Attestation Platform
  3. Configuring Policy Management

Creating an Intermediate CA

As a best practice, SecureW2 recommends having a new intermediate CA for TPM-based attestation.

To create a new intermediate CA:

  1. Log in to the JoinNow Management Portal.
  2. Navigate to Dynamic PKI > Certificate Authorities. 
  3. Click Add Certificate Authority.
  4. In the Basic section, select the Device and User Authentication option from the Generate CA For drop-down list to authenticate devices and users.
  5. From the Type drop-down list, select Intermediate CA.
  6. From the Certificate Authority drop-down list, select the default Root CA for your organization.
  7. In the Common Name field, enter a common name for the CA certificate. 
  8. From the Key Size drop-down list, select 2048 for the CA certificate key pair. 
  9. From the Signature Algorithm drop-down list, select the signature algorithm for the certificate signing request. The option available is SHA-256.
  10. In the Validity Period (in years) field, enter the validity period of the CA certificate.
  11. Click Save. The new intermediate CA is generated.

Configure Key Attestation Platform

This section describes the steps to configure a key attestation platform for TPM.

  1. Navigate to Integration Hub > Key Attestation Platforms. 
  2. Click Add.

    Figure: Key Attestation Platform Page
  3. In the Name field, enter a name for the key attestation platform.
  4. In the Display Description field, enter a suitable description for the key attestation platform.
  5. From the Type drop-down list, select TPM.
  6. From the Manufacturer drop-down list, select the trusted vendor that manufactured the TPM chip. SecureW2 currently supports AMD and Infineon.

     

    NOTE: Select Other in the Manufacturer field and manually enter a manufacturer that is not listed.

     

    Figure: Adding a TPM key attestation Platform
  7. Click Save. The Token Details pop-up appears. Copy the API secret and Enrollment URI values into a text editor, as they are required for TPM enrollment.

Configuring Custom TPM Manufacturer

If the TPM chip’s manufacturer is not listed in the Manufacturer drop-down, Admin can select Other to manually enter the manufacturer, add the Manufacturer Root CA, and specify the whitelisted domains for the AIA URL.

This section describes the steps to configure a custom manufacturer for TPM.

  1. Navigate to Integration Hub > Key Attestation Platforms. 
  2. Click Add.
  3. In the Name field, enter a name for the key attestation platform.
  4. In the Display Description field, enter a suitable description for the key attestation platform.
  5. From the Type drop-down list, select TPM.
  6. From the Manufacturer drop-down list, select Other.
  7. In the Manufacturer Name field, enter the manufacturer’s name.

    Figure: Adding a TPM key attestation provider for a custom manufacturer

  8. Click Save. The Token Details pop-up appears. Copy the API secret and Enrollment URI values into a text editor, as they are required for TPM enrollment.

    Figure: Token details dialog box

  9. Click the Configuration tab.
    1. In the Manufacturer Root CA field, click Choose file to locate and upload the root certificate.
    2. In the Whitelisted Domains field, enter the whitelisted domain and click Upload.
  10. Click Update.

Configuring Policy Management

The following policies must be created in JoinNow for TPM-based certificate enrollment.

  1. Policy Workflows
  2. Device Role 
  3. Enrollment

Creating a Policy Workflow

  1. Go to Policy Management > Policy Workflows.
  2. Click Add Policy Engine Workflows.
  3. In the Basic section, in the Name field, enter a name for the policy.
  4. In the Description field, enter a description for the policy.
  5. Click Save. The page refreshes and automatically selects the Conditions tab.
  6. In the Conditions section, click the Core Provider drop-down and select the Device Management Platform auto-created with the same name as the Key attestation platform.
  7. Click Update.

Creating a Device Role Policy

Device Role Policy helps in mapping the attestation provider in JoinNow for device attestation.

  1. From the JoinNow Management Portal, go to Policy Management > Device Roles.
  2. Click Add Device Role Policy.
  3. In the Basic tab, enter a name in the Name field.
  4. For Display Description, enter a description.
  5. Click Save. The page refreshes, and the Conditions tab opens.
  6. Click on the Conditions tab.
  7. From the Identity drop-down, select the Key Attestation Provider created in the 2.1 Configure Key Attestation Platform section.
  8. Click Update.

Creating an Enrollment

  1. From the JoinNow Management Portal, go to Policy Management > Enrollment.
  2. Click Add Enrollment Policy.
  3. In the Basic tab, for Name, enter a name.
  4. For Description, enter a description.
  5. Click Save. The page refreshes and displays the Conditions and Settings tab.
  6. In the Conditions section, for Role, select the user role policy you created in the Creating a Policy Workflow section.
  7. For Device Role, select the device role created in the Creating a Device Role Policy section.
  8. Click on the Settings tab.
  9. From the Use Certificate Authority drop-down, select the Certificate Authority created for TPM.
  10. From the Use Certificate Template drop-down list, choose the DEFAULT CREATE CERTIFICATE TEMPLATE 1.
  11. Click Update.

Importing TPM IoT Agent from JoinNow

To download the TPM agent required for a Linux machine:

  1. Navigate to Downloads > Enrollment Gateway.
  2. Click the Download button adjacent to the TPM Agent.

Configuring Linux

The following steps configure a Linux machine for TPM-based certificate enrollment.

  1. Install TPM 2.0 tools using the following command – sudo apt install tpm2-tools.
  2. To verify the TPM Manufacturer, use the “tpm2_getcap properties-fixed” command. 

    Example output:

    1. TPM_IFX → Infineon
    2. TPM_AMD → AMD
  3. Import and extract the ZIP file downloaded from the JoinNow Management Portal in 2.3.4 Importing TPM IoT Agent from JoinNow. The following files will be extracted:
      1. Sp
      2. verify-tpm.sh
  4. Create a folder using the “mkdir tpm-enroll” command.
  5. Move the files to the created folder using “mv sp verify-tpm.sh tpm-enroll/”
  6. Enter the folder using “cd tpm-enroll”
  7. Run the following enrollment command:
				
					./sp enroll \
 --url "Enrollment URI" \
 --identity "user@example.com" \
 --psk "API Secret" \
 --output-dir .


NOTE: Use the Enrollment URL and API Secret created earlier in 2.2 Configure Key Attestation Platform.

Sample Command:

				
					./sp enroll \
 --url "https://api.securew2.com/urltokenid/xxx/enroll/xxx" \
 --identity "testamd@securew2.com" \
 --psk "your_api_secret" \
 --output-dir .

Enhanced Events

Admins can check the enrollment success message on the Enhanced Events page under Data and Monitoring:

More SecureW2 Documentation Explainers