快速入门:使用 Azure IoT C SDK 预配模拟的 TPM 设备Quickstart: Provision a simulated TPM device using the Azure IoT C SDK

本快速入门介绍如何在 Windows 开发计算机上创建和运行受信任平台模块 (TPM) 设备模拟器。In this quickstart, you will learn how to create and run a Trusted Platform Module (TPM) device simulator on a Windows development machine. 然后使用设备预配服务实例将此模拟设备连接到 IoT 中心。You will connect this simulated device to an IoT hub using a Device Provisioning Service instance. 我们将借助 Azure IoT C SDK 中的示例代码在设备预配服务实例中注册设备,并模拟设备的启动序列。Sample code from the Azure IoT C SDK will be used to help enroll the device with a Device Provisioning Service instance and simulate a boot sequence for the device.

如果不熟悉自动预配过程,请查看自动预配的概念If you're unfamiliar with the process of autoprovisioning, review Auto-provisioning concepts. 另外,在继续学习本快速入门之前,请确保已完成通过 Azure 门户设置 IoT 中心设备预配服务中的步骤。Also, make sure you've completed the steps in Set up IoT Hub Device Provisioning Service with the Azure portal before continuing with this quickstart.

Azure IoT 设备预配服务支持两类注册:The Azure IoT Device Provisioning Service supports two types of enrollments:

本文将演示单个注册。This article will demonstrate individual enrollments.

如果没有 Azure 订阅,可在开始前创建一个试用帐户If you don't have an Azure subscription, create a trial account before you begin.

先决条件Prerequisites

为 Azure IoT C SDK 准备开发环境Prepare a development environment for the Azure IoT C SDK

在本部分,我们将准备一个用于生成 Azure IoT C SDKTPM 设备模拟器示例的开发环境。In this section, you will prepare a development environment used to build the Azure IoT C SDK and the TPM device simulator sample.

  1. 下载 CMake 生成系统Download the CMake build system.

    在进行 CMake 安装之前,必须在计算机上安装 Visual Studio 必备组件(Visual Studio 和“使用 C++ 的桌面开发”工作负荷)。It is important that the Visual Studio prerequisites (Visual Studio and the 'Desktop development with C++' workload) are installed on your machine, before starting the CMake installation. 满足先决条件并验证下载内容后,安装 CMake 生成系统。Once the prerequisites are in place, and the download is verified, install the CMake build system.

  2. 打开命令提示符或 Git Bash shell。Open a command prompt or Git Bash shell. 执行以下命令克隆 Azure IoT C SDK GitHub 存储库:Execute the following command to clone the Azure IoT C SDK GitHub repository:

    git clone https://github.com/Azure/azure-iot-sdk-c.git --recursive
    

    应该预料到此操作需要几分钟才能完成。You should expect this operation to take several minutes to complete.

  3. 在 git 存储库的根目录中创建 cmake 子目录,并导航到该文件夹。Create a cmake subdirectory in the root directory of the git repository, and navigate to that folder.

    cd azure-iot-sdk-c
    mkdir cmake
    cd cmake
    

生成 SDK 并运行 TPM 设备模拟器Build the SDK and run the TPM device simulator

在本部分,我们将生成包含 TPM 设备模拟器示例代码的 Azure IoT C SDK。In this section, you will build the Azure IoT C SDK, which includes the TPM device simulator sample code. 此示例通过共享访问签名 (SAS) 令牌身份验证提供 TPM 证明机制This sample provides a TPM attestation mechanism via Shared Access Signature (SAS) Token authentication.

  1. 从 azure-iot-sdk-c git 存储库中创建的 cmake 子目录,运行以下命令以生成示例。From the cmake subdirectory you created in the azure-iot-sdk-c git repository, run the following command to build the sample. 此生成命令还将生成模拟设备的 Visual Studio 解决方案。A Visual Studio solution for the simulated device will also be generated by this build command.

    cmake -Duse_prov_client:BOOL=ON -Duse_tpm_simulator:BOOL=ON ..
    

    如果 cmake 找不到 C++ 编译器,则可能会在运行以上命令时出现生成错误。If cmake does not find your C++ compiler, you might get build errors while running the above command. 如果出现这种情况,请尝试在 Visual Studio 命令提示符窗口中运行该命令。If that happens, try running this command in the Visual Studio command prompt.

    生成成功后,最后的几个输出行如下所示:Once the build succeeds, the last few output lines will look similar to the following output:

    $ cmake -Duse_prov_client:BOOL=ON -Duse_tpm_simulator:BOOL=ON ..
    -- Building for: Visual Studio 15 2017
    -- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
    -- The C compiler identification is MSVC 19.12.25835.0
    -- The CXX compiler identification is MSVC 19.12.25835.0
    
    ...
    
    -- Configuring done
    -- Generating done
    -- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake
    
  2. 导航到克隆的 git 存储库的根文件夹,并使用如下所示的路径运行 TPM 模拟器。Navigate to the root folder of the git repository you cloned, and run the TPM simulator using the path shown below. 此模拟器通过端口 2321 和 2322 上的套接字进行侦听。This simulator listens over a socket on ports 2321 and 2322. 请勿关闭此命令窗口;本快速入门自始至终都需要让此模拟器保持运行。Do not close this command window; you will need to keep this simulator running until the end of this quickstart.

    如果在 cmake 文件夹中,则请运行以下命令:If you are in the cmake folder, then run the following commands:

    cd ..
    .\provisioning_client\deps\utpm\tools\tpm_simulator\Simulator.exe
    

    模拟器未返回任何输出。You will not see any output from the simulator. 请让它继续模拟 TPM 设备。Let it continue to run simulating a TPM device.

从 TPM 设备读取加密密钥Read cryptographic keys from the TPM device

在本部分,我们将生成并执行一个示例,以便从保持运行的、通过端口 2321 和 2322 侦听的 TPM 模拟器中读取认可密钥和注册 ID。In this section, you will build and execute a sample that will read the endorsement key and registration ID from the TPM simulator you left running, and listening over ports 2321 and 2322. 这些值用于将设备注册到设备预配服务实例。These values will be used for device enrollment with your Device Provisioning Service instance.

  1. 启动 Visual Studio 并打开名为 azure_iot_sdks.sln 的新解决方案文件。Launch Visual Studio and open the new solution file named azure_iot_sdks.sln. 此解决方案文件位于先前在 azure-iot-sdk-c git 存储库的根目录中创建的 cmake 文件夹中。This solution file is located in the cmake folder you previously created in the root of the azure-iot-sdk-c git repository.

  2. 在 Visual Studio 菜单中,选择“生成” > “生成解决方案”以生成解决方案中的所有项目。 On the Visual Studio menu, select Build > Build Solution to build all projects in the solution.

  3. 在 Visual Studio 的“解决方案资源管理器”窗口中,导航到 Provision_Tools 文件夹。 In Visual Studio's Solution Explorer window, navigate to the Provision_Tools folder. 右键单击“tpm_device_provision”项目, 然后选择“设为启动项目”。 Right-click the tpm_device_provision project and select Set as Startup Project.

  4. 在 Visual Studio 菜单中,选择“调试” > “开始执行(不调试)”以运行该解决方案。 On the Visual Studio menu, select Debug > Start without debugging to run the solution. 应用将读取并显示 注册 ID认可密钥The app reads and displays a Registration ID and an Endorsement Key. 复制这些值。Copy these values. 在下一部分,这些值将用于设备注册。They will be used in the next section for device enrollment.

在门户中创建设备注册项Create a device enrollment entry in the portal

  1. 登录到 Azure 门户,单击左侧菜单上的“所有资源”按钮,打开设备预配服务 。Sign in to the Azure portal, click on the All resources button on the left-hand menu and open your Device Provisioning service.

  2. 选择“管理注册”选项卡,然后单击顶部的“添加个人注册”按钮。 Select the Manage enrollments tab, and then click the Add individual enrollment button at the top.

  3. 在“添加注册”中输入以下信息,然后单击“保存”按钮。 On Add enrollment, enter the following information, and click the Save button.

    • 机制: 选择“TPM” 作为标识证明机制Mechanism: Select TPM as the identity attestation Mechanism.

    • 认可密钥: 输入通过运行 tpm_device_provision 项目为 TPM 设备生成的“认可密钥” 。Endorsement key: Enter the Endorsement key you generated for your TPM device by running the tpm_device_provision project.

    • 注册 ID: 输入通过运行 tpm_device_provision 项目为 TPM 设备生成的“注册 ID” 。Registration ID: Enter the Registration ID you generated for your TPM device by running the tpm_device_provision project.

    • IoT Edge 设备: 选择“禁用”。 IoT Edge device: Select Disable.

    • IoT 中心设备 ID: 输入 test-docs-device 作为设备的 ID 。IoT Hub Device ID: Enter test-docs-device to give the device an ID.

      在门户中输入设备注册信息

      成功注册以后,设备的“注册 ID”会显示在“单个注册”选项卡下的列表中。 On successful enrollment, the Registration ID of your device will appear in the list under the Individual Enrollments tab.

模拟设备的首次启动顺序Simulate first boot sequence for the device

在本部分,我们将示例代码配置为使用高级消息队列协议 (AMQP) 向设备预配服务实例发送设备的启动序列。In this section, you will configure sample code to use the Advanced Message Queuing Protocol (AMQP) to send the device's boot sequence to your Device Provisioning Service instance. 此启动序列使得设备可被识别并分配到与设备预配服务实例链接的 IoT 中心。This boot sequence will cause the device to be recognized and assigned to an IoT hub linked to the Device Provisioning Service instance.

  1. 在 Azure 门户中,选择设备预配服务的“概述”选项卡,并复制“ID 范围”值。 In the Azure portal, select the Overview tab for your Device Provisioning service and copy the ID Scope value.

    从门户中提取设备预配服务终结点信息

  2. 在 Visual Studio 的“解决方案资源管理器”窗口中,导航到 Provision_Samples 文件夹。 In Visual Studio's Solution Explorer window, navigate to the Provision_Samples folder. 展开名为 prov_dev_client_sample 的示例项目。Expand the sample project named prov_dev_client_sample. 展开“源文件”,打开 prov_dev_client_sample.cExpand Source Files, and open prov_dev_client_sample.c.

  3. 在该文件的顶部附近,找到每个设备协议的 #define 语句,如下所示。Near the top of the file, find the #define statements for each device protocol as shown below. 确保仅取消注释 SAMPLE_AMQPMake sure only SAMPLE_AMQP is uncommented.

    目前,TPM 个人注册不支持 MQTT 协议Currently, the MQTT protocol is not supported for TPM Individual Enrollment.

    //
    // The protocol you wish to use should be uncommented
    //
    //#define SAMPLE_MQTT
    //#define SAMPLE_MQTT_OVER_WEBSOCKETS
    #define SAMPLE_AMQP
    //#define SAMPLE_AMQP_OVER_WEBSOCKETS
    //#define SAMPLE_HTTP
    
  4. 找到 id_scope 常量,将值替换为前面复制的“ID 范围”值。 Find the id_scope constant, and replace the value with your ID Scope value that you copied earlier.

    static const char* id_scope = "0ne00002193";
    
  5. 在同一文件中找到 main() 函数的定义。Find the definition for the main() function in the same file. 确保 hsm_type 变量设置为 SECURE_DEVICE_TYPE_TPM 而不是 SECURE_DEVICE_TYPE_X509,如下所示。Make sure the hsm_type variable is set to SECURE_DEVICE_TYPE_TPM instead of SECURE_DEVICE_TYPE_X509 as shown below.

    SECURE_DEVICE_TYPE hsm_type;
    hsm_type = SECURE_DEVICE_TYPE_TPM;
    //hsm_type = SECURE_DEVICE_TYPE_X509;
    
  6. 右键单击“prov_dev_client_sample”项目, 然后选择“设为启动项目”。 Right-click the prov_dev_client_sample project and select Set as Startup Project.

  7. 在 Visual Studio 菜单中,选择“调试” > “开始执行(不调试)”以运行该解决方案。 On the Visual Studio menu, select Debug > Start without debugging to run the solution. 在重新生成项目的提示中单击“是”,以便在运行项目之前重新生成项目。 In the prompt to rebuild the project, click Yes, to rebuild the project before running.

    以下输出示例显示预配设备客户端示例成功启动,然后连接到设备预配服务实例来获取 IoT 中心信息并注册:The following output is an example of the provisioning device client sample successfully booting up, and connecting to a Device Provisioning Service instance to get IoT hub information and registering:

    Provisioning API Version: 1.2.7
    Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
    
    Registering... Press enter key to interrupt.
    
    Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
    Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
    Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
    
    Registration Information received from service:
    test-docs-hub.azure-devices.net, deviceId: test-docs-device
    
  8. 预配服务将模拟设备预配到 IoT 中心后,中心的“IoT 设备”中会显示设备 ID。 Once the simulated device is provisioned to the IoT hub by your provisioning service, the device ID appears with the hub's IoT Devices.

    设备注册到 IoT 中心

清理资源Clean up resources

如果打算继续使用和探索设备客户端示例,请勿清理在本快速入门中创建的资源。If you plan to continue working on and exploring the device client sample, do not clean up the resources created in this Quickstart. 如果不打算继续学习,请通过以下步骤删除通过本快速入门创建的所有资源。If you do not plan to continue, use the following steps to delete all resources created by this Quickstart.

  1. 关闭计算机上的设备客户端示例输出窗口。Close the device client sample output window on your machine.
  2. 关闭计算机上的 TPM 模拟器窗口。Close the TPM simulator window on your machine.
  3. 在 Azure 门户的左侧菜单中单击“所有资源”,然后选择设备预配服务 。From the left-hand menu in the Azure portal, click All resources and then select your Device Provisioning service. 打开服务的“管理注册”,然后单击“个人注册”选项卡。 选择在本快速入门中注册的设备的“注册 ID”,然后单击顶部的“删除”按钮。 Open Manage Enrollments for your service, and then click the Individual Enrollments tab. Select the REGISTRATION ID of the device you enrolled in this Quickstart, and click the Delete button at the top.
  4. 在 Azure 门户的左侧菜单中单击“所有资源”,然后选择 IoT 中心 。From the left-hand menu in the Azure portal, click All resources and then select your IoT hub. 打开中心的“IoT 设备”,选择在本快速入门中注册的设备的“设备 ID”,然后单击顶部的“删除”按钮。 Open IoT Devices for your hub, select the DEVICE ID of the device you registered in this Quickstart, and then click Delete button at the top.

后续步骤Next steps

在本快速入门中,你已在计算机上创建 TPM 模拟设备,并已使用 IoT 中心设备预配服务将其预配到 IoT 中心。In this Quickstart, you’ve created a TPM simulated device on your machine and provisioned it to your IoT hub using the IoT Hub Device Provisioning Service. 若要了解如何以编程方式注册 TPM 设备,请继续阅读快速入门中关于 TPM 设备的编程注册内容。To learn how to enroll your TPM device programmatically, continue to the Quickstart for programmatic enrollment of a TPM device.