dTPM access for Azure IoT Edge for Linux on Windows

Applies to: IoT Edge 1.5

Important

IoT Edge 1.5 LTS is the supported release. IoT Edge 1.4 LTS is end of life as of November 12, 2024. If you are on an earlier release, see Update IoT Edge.

A trusted platform module (TPM) chip is a secure crypto-processor that carries out cryptographic operations. This technology provides hardware-based security functions. The Azure IoT Edge for Linux on Windows (EFLOW) virtual machine doesn't have a virtual TPM attached. However, you can enable or disable the TPM passthrough feature, which lets the EFLOW virtual machine use the Windows host OS TPM. The TPM passthrough feature lets you:

• Use TPM technology for IoT Edge device provisioning with Device Provisioning Service (DPS)
• Get read-only access to cryptographic keys stored in the TPM

This article shows you how to write sample C# code to read cryptographic keys stored in the device TPM.

Important

Access to TPM keys is limited to read-only. To write keys to the TPM, do it from the Windows host OS.

Prerequisites

• A Windows host OS with a TPM or vTPM (if you use a Windows host OS virtual machine).

• An EFLOW virtual machine with TPM passthrough enabled. In an elevated PowerShell session, run Set-EflowVmFeature -feature "DpsTpm" -enable to enable TPM passthrough. For more information, see Set-EflowVmFeature to enable TPM passthrough.

• Make sure the NV index (default index=3001) is initialized with 8 bytes of data. The default AuthValue used by the sample is {1,2,3,4,5,6,7,8}, which matches the NV (Windows) sample in the TSS.MSR libraries when writing to the TPM. Initialize all indexes on the Windows host before reading from the EFLOW VM. For more information about TPM samples, see TSS.MSR.

  Warning

  Enabling TPM passthrough to the virtual machine can increase security risks.

Create the dTPM executable

Follow these steps to create a sample executable to access a TPM index from the EFLOW VM. For more information about EFLOW TPM passthrough, see Azure IoT Edge for Linux on Windows Security.

1. Open Visual Studio 2019 or 2022.

2. Select Create a new project.

3. Choose Console App in the list of templates, and then select Next.

   

4. Fill in the Project Name, Location, and Solution Name fields, and then select Next.

5. Choose a target framework. The latest .NET 6.0 LTS version is preferred. After you choose a target framework, select Create. Visual Studio creates a new console app solution.

6. In Solution Explorer, right-click the project name and select Manage NuGet Packages.

7. Select Browse, and then search for Microsoft.TSS. For more information about this package, see Microsoft.TSS.

8. Choose the Microsoft.TSS package from the list, and then select Install.

   

9. Edit the Program.cs file, and replace the contents with the EFLOW TPM sample code - Program.cs.

10. Select Build > Build solution to build the project. Verify that the build is successful.

11. In Solution Explorer, right-click the project, and then select Publish.

12. In the Publish wizard, choose Folder > Folder. Select Browse, and choose an output location for the executable file to be generated. Select Finish. After the publish profile is created, select Close.

13. On the Publish tab, select Show all settings link. Change the following configurations then select Save.

    • Target Runtime: linux-x64.
    • Deployment mode: Self-contained.

    

14. Select Publish, and then wait for the executable to be created.

If publishing succeeds, you see the new files in your output folder.

Copy and run the executable

Once the executable file and dependency files are created, you need to copy the folder to the EFLOW virtual machine. The following steps show you how to copy all the necessary files and how to run the executable inside the EFLOW virtual machine.

1. Start an elevated PowerShell session using Run as Administrator.

2. Change directory to the parent folder that contains the published files. For example, if your published files are under the folder TPM in the directory C:\Users\User. You can use the following command to change to the parent folder.

   cd "C:\Users\User"
   

3. Create a tar file with all the files created in previous steps. For example, if you have all your files under the folder TPM, you can use the following command to create the TPM.tar file.

    tar -cvzf TPM.tar ".\TPM"
   

4. Once the TPM.tar file is created successfully, use the Copy-EflowVmFile cmdlet to copy the tar file created to the EFLOW VM. For example, if you have the tar file name TPM.tar in the directory C:\Users\User. you can use the following command to copy to the EFLOW VM.

   Copy-EflowVmFile -fromFile "C:\Users\User\TPM.tar" -toFile "/home/iotedge-user/" -pushFile
   

5. Connect to the EFLOW virtual machine.

   Connect-EflowVm
   

6. Change directory to the folder where you copied the tar file and check that the file is available. If you used the previous example, when you connect to the EFLOW VM, you're already at the iotedge-user root folder. Run the ls command to list the files and folders.

7. Run the following command to extract all the content from the tar file.

   tar -xvzf TPM.tar
   

8. After extraction, you should see a new folder with all the TPM files.

9. Change directory to the TPM folder.

   cd TPM
   

10. Add executable permission to the main executable file. For example, if your project name was TPMRead, your main executable is named TPMRead. Run the following command to make it executable.

    chmod +x TPMRead
    

11. To solve an ICU globalization issue, run the following command. For example, if your project name is TPMTest run:

     sed -i '/"configProperties": /a \\t"System.Globalization.Invariant\": true,' TPMTest.runtimeconfig.json
    

12. The last step is to run the executable file. For example, if your project name is TPMTest, run the following command:

    ./TPMTest
    

    You should see an output similar to the following.

    

Next steps

Learn how to develop IoT Edge modules with Linux containers using IoT Edge for Linux on Windows.