Create and provision IoT Edge devices at scale with a TPM on Windows

Applies to: IoT Edge 1.1

Important

IoT Edge 1.1 end of support date was December 13, 2022. Check the Microsoft Product Lifecycle for information about how this product, service, technology, or API is supported. For more information about updating to the latest version of IoT Edge, see Update IoT Edge.

This article provides instructions for autoprovisioning an Azure IoT Edge for Windows device by using a Trusted Platform Module (TPM). You can automatically provision IoT Edge devices with the Azure IoT Hub device provisioning service. If you're unfamiliar with the process of autoprovisioning, review the provisioning overview before you continue.

Note

Azure IoT Edge with Windows containers will not be supported starting with version 1.2 of Azure IoT Edge.

Consider using the new method for running IoT Edge on Windows devices, Azure IoT Edge for Linux on Windows.

If you want to use Azure IoT Edge for Linux on Windows, you can follow the steps in the equivalent how-to guide.

This article outlines two methodologies. Select your preference based on the architecture of your solution:

• Autoprovision a Windows device with physical TPM hardware.
• Autoprovision a Windows device running a simulated TPM. We recommend this methodology only as a testing scenario. A simulated TPM doesn't offer the same security as a physical TPM.

Instructions differ based on your methodology, so make sure you're on the correct tab going forward.

The tasks are as follows:

Physical TPM

• Retrieve your device's provisioning information.
• Create an individual enrollment for the device.
• Install the IoT Edge runtime and connect the device to IoT Hub.

Simulated TPM

• Set up your simulated TPM and retrieve its provisioning information.
• Create an individual enrollment for the device.
• Install the IoT Edge runtime and connect the device to IoT Hub.

Prerequisites

The prerequisites are the same for physical TPM and virtual TPM solutions.

Cloud resources

• An active IoT hub
• An instance of the IoT Hub device provisioning service in Azure, linked to your IoT hub
  • If you don't have a device provisioning service instance, you can follow the instructions in the Create a new IoT Hub device provisioning service and Link the IoT hub and your device provisioning service sections of the IoT Hub device provisioning service quickstart.
  • After you have the device provisioning service running, copy the value of ID Scope from the overview page. You use this value when you configure the IoT Edge runtime.

Device requirements

A Windows development machine. This article uses Windows 10.

Note

TPM 2.0 is required when you use TPM attestation with the device provisioning service.

You can only create individual, not group, device provisioning service enrollments when you use a TPM.

Set up your TPM

Physical TPM

In this section, you build a tool that you can use to retrieve the registration ID and endorsement key for your TPM.

1. Follow the steps in Set up a Windows development environment to install and build the Azure IoT device SDK for C.

2. Run the following commands in an elevated PowerShell session to build the SDK tool that retrieves your device provisioning information for your TPM.

   cd azure-iot-sdk-c\cmake
   cmake -Duse_prov_client:BOOL=ON ..
   cd provisioning_client\tools\tpm_device_provision
   make
   .\tpm_device_provision
   

3. The output window displays the device's Registration ID and the Endorsement key. Copy these values for use later when you create an individual enrollment for your device in the device provisioning service.

Tip

If you don't want to use the SDK tool to retrieve the information, you need to find another way to obtain the provisioning information. The endorsement key, which is unique to each TPM chip, is obtained from the TPM chip manufacturer associated with it. You can derive a unique registration ID for your TPM device. For example, you can create an SHA-256 hash of the endorsement key.

After you have your registration ID and endorsement key, you're ready to continue.

Simulated TPM

If you don't have a physical TPM available and want to test this provisioning method, you can simulate a TPM on your device.

The IoT Hub device provisioning service provides samples that simulate a TPM and return the endorsement key and registration ID for you.

1. Choose one of the samples from the following list based on your preferred language.
2. Stop following the device provisioning service sample steps after you have the simulated TPM running and have collected the Endorsement key and Registration ID. Don't select Enter to run registration in the sample application.
3. Keep the window hosting the simulated TPM running until you're finished testing this scenario.
4. Return to this article to create a device provisioning service enrollment and configure your device.

Simulated TPM samples:

• C
• Java
• C#
• Node.js
• Python

Create a device provisioning service enrollment

Use your TPM's provisioning information to create an individual enrollment in the device provisioning service.

When you create an enrollment in the device provisioning service, you have the opportunity to declare an Initial Device Twin State. In the device twin, you can set tags to group devices by any metric used in your solution, like region, environment, location, or device type. These tags are used to create automatic deployments.

Tip

The steps in this article are for the Azure portal, but you can also create individual enrollments by using the Azure CLI. For more information, see az iot dps enrollment. As part of the CLI command, use the edge-enabled flag to specify that the enrollment is for an IoT Edge device.

1. In the Azure portal, go to your instance of the IoT Hub device provisioning service.

2. Under Settings, select Manage enrollments.

3. Select Add individual enrollment, and then complete the following steps to configure the enrollment:

   1. For Mechanism, select TPM.

   2. Provide the Endorsement key and Registration ID that you copied from your VM or physical device.

   3. Provide an ID for your device if you want. If you don't provide a device ID, the registration ID is used.

   4. Select True to declare that your VM or physical device is an IoT Edge device.

   5. Choose the linked IoT hub that you want to connect your device to, or select Link to new IoT Hub. You can choose multiple hubs, and the device will be assigned to one of them according to the selected assignment policy.

   6. Add a tag value to the Initial Device Twin State if you want. You can use tags to target groups of devices for module deployment. For more information, see Deploy IoT Edge modules at scale.

   7. Select Save.

Now that an enrollment exists for this device, the IoT Edge runtime can automatically provision the device during installation.

Install IoT Edge

In this section, you prepare your Windows VM or physical device for IoT Edge. Then, you install IoT Edge.

Azure IoT Edge relies on an OCI-compatible container runtime. Moby, a Moby-based engine, is included in the installation script, which means there are no additional steps to install the engine.

To install the IoT Edge runtime:

1. Run PowerShell as an administrator.

   Use an AMD64 session of PowerShell, not PowerShell(x86). If you're unsure which session type you're using, run the following command:

   (Get-Process -Id $PID).StartInfo.EnvironmentVariables["PROCESSOR_ARCHITECTURE"]
   

2. Run the Deploy-IoTEdge command, which performs the following tasks:

   • Checks that your Windows machine is on a supported version
   • Turns on the containers feature
   • Downloads the moby engine and the IoT Edge runtime

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Deploy-IoTEdge
   

3. Restart your device if prompted.

When you install IoT Edge on a device, you can use additional parameters to modify the process including:

• Direct traffic to go through a proxy server
• Point the installer to a local directory for offline installation

For more information about these additional parameters, see PowerShell scripts for IoT Edge with Windows containers.

Provision the device with its cloud identity

After the runtime is installed on your device, configure the device with the information it uses to connect to the device provisioning service and IoT Hub.

1. Know your device provisioning service ID Scope and device Registration ID that were gathered in the previous sections.

2. Open a PowerShell window in administrator mode. Be sure to use an AMD64 session of PowerShell when you install IoT Edge, not PowerShell (x86).

3. The Initialize-IoTEdge command configures the IoT Edge runtime on your machine. The command defaults to manual provisioning with Windows containers. Use the -Dps flag to use the device provisioning service instead of manual provisioning.

   Replace the placeholder values for paste_scope_id_here and paste_registration_id_here with the data you collected earlier.

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Initialize-IoTEdge -Dps -ScopeId paste_scope_id_here -RegistrationId paste_registration_id_here
   

Verify successful installation

If the runtime started successfully, go into your IoT hub and start deploying IoT Edge modules to your device. Use the following commands on your device to verify that the runtime installed and started successfully.

1. Check the status of the IoT Edge service.

   Get-Service iotedge
   

2. Examine service logs from the last 5 minutes.

   . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog
   

3. List running modules.

   iotedge list
   

Next steps

The device provisioning service enrollment process lets you set the device ID and device twin tags at the same time as you provision the new device. You can use those values to target individual devices or groups of devices by using automatic device management.

Learn how to deploy and monitor IoT Edge modules at scale by using the Azure portal or the Azure CLI.