使用 Azure IoT 中心设备预配服务设置设备以进行预配Set up a device to provision using the Azure IoT Hub Device Provisioning Service

前面的教程介绍了设置 Azure IoT 中心设备预配服务以将设备自动预配到 IoT 中心的方法。In the previous tutorial, you learned how to set up the Azure IoT Hub Device Provisioning Service to automatically provision your devices to your IoT hub. 本教程介绍如何在制造过程中设置设备,使之能够通过 IoT 中心进行自动预配。This tutorial shows you how to set up your device during the manufacturing process, enabling it to be auto-provisioned with IoT Hub. 设备在首先启动并连接到预配服务之后,即可根据其证明机制进行预配。Your device is provisioned based on its Attestation mechanism, upon first boot and connection to the provisioning service. 本教程涵盖以下任务:This tutorial covers the following tasks:

  • 生成特定于平台的设备预配服务客户端 SDKBuild platform-specific Device Provisioning Services Client SDK
  • 提取安全项目Extract the security artifacts
  • 创建设备注册软件Create the device registration software

本教程假设你已根据以前的设置云资源教程中的说明创建了设备预配服务实例和 IoT 中心。This tutorial expects that you have already created your Device Provisioning Service instance and an IoT hub, using the instructions in the previous Set up cloud resources tutorial.

本教程使用用于 C 存储库的 Azure IoT SDK 和库,该存储库包含用于 C 的设备预配服务客户端 SDK。此 SDK 目前为运行在 Windows 或 Ubuntu 实现上的设备提供 TPM 和 X.509 支持。This tutorial uses the Azure IoT SDKs and libraries for C repository, which contains the Device Provisioning Service Client SDK for C. The SDK currently provides TPM and X.509 support for devices running on Windows or Ubuntu implementations. 本教程以 Windows 开发客户端的使用为基础,而使用该客户端的前提是基本熟悉 Visual Studio 的使用。This tutorial is based on use of a Windows development client, which also assumes basic proficiency with Visual Studio.

如果不熟悉自动预配过程,请务必在继续操作之前查看自动预配概念If you're unfamiliar with the process of auto-provisioning, be sure to review Auto-provisioning concepts before continuing.

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

先决条件Prerequisites

生成特定于平台的 SDK 版本Build a platform-specific version of the SDK

设备预配服务客户端 SDK 有助于实现设备注册软件。The Device Provisioning Service Client SDK helps you implement your device registration software. 但在使用它之前,需根据开发客户端平台和证明机制生成一个 SDK 版本。But before you can use it, you need to build a version of the SDK specific to your development client platform and attestation mechanism. 在本教程中,请针对支持的证明类型生成一个使用 Visual Studio(基于 Windows 开发平台)的 SDK:In this tutorial, you build an SDK that uses Visual Studio on a Windows development platform, for a supported type of attestation:

  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
    
  4. 基于你将使用的认证机制构建适用于你的开发平台的 SDK。Build the SDK for your development platform based on the attestation mechanisms you will be using. 使用下列命令之一(另请注意,每个命令有两个尾随的句点字符)。Use one of the following commands (also note the two trailing period characters for each command). 在完成后,CMake 会使用特定于设备的内容生成 /cmake 子目录:Upon completion, CMake builds out the /cmake subdirectory with content specific to your device:

    • 对于使用 TPM 模拟器进行证明的设备:For devices that use the TPM simulator for attestation:

      cmake -Duse_prov_client:BOOL=ON -Duse_tpm_simulator:BOOL=ON ..
      
    • 对于任何其他设备(物理 TPM/HSM/X.509 或模拟的 X.509 证书):For any other device (physical TPM/HSM/X.509, or a simulated X.509 certificate):

      cmake -Duse_prov_client:BOOL=ON ..
      

现在可以使用 SDK 生成设备注册代码了。Now you're ready to use the SDK to build your device registration code.

提取安全项目Extract the security artifacts

下一步是提取设备所用的证明机制的安全项目。The next step is to extract the security artifacts for the attestation mechanism used by your device.

物理设备Physical devices

收集安全项目的过程如下所述,具体取决于你构建 SDK 的目的是对物理 TPM/HSM 进行认证还是使用 X.509 证书进行认证:Depending on whether you built the SDK to use attestation for a physical TPM/HSM or using X.509 certificates, gathering the security artifacts is as follows:

  • 对于 TPM 设备,需要通过 TPM 芯片制造商确定与其关联的“认可密钥” 。For a TPM device, you need to determine the Endorsement Key associated with it from the TPM chip manufacturer. 通过对认可密钥进行哈希处理,可为 TPM 设备派生唯一的“注册 ID” 。You can derive a unique Registration ID for your TPM device by hashing the endorsement key.

  • 对于 X.509 设备,你需要获取为设备颁发的证书。For an X.509 device, you need to obtain the certificates issued to your device(s). 预配服务公开了两种类型的注册条目,它们使用 X.509 认证机制控制对设备的访问。The provisioning service exposes two types of enrollment entries that control access for devices using the X.509 attestation mechanism. 所需的证书取决于你将使用的注册类型。The certificates needed depend on the enrollment types you will be using.

    1. 单独注册:针对特定的单个设备的注册。Individual enrollments: Enrollment for a specific single device. 此类型的注册条目需要最终实体、“叶”、证书This type of enrollment entry requires end-entity, "leaf", certificates.
    2. 注册组:此类型的注册条目需要中间或根证书。Enrollment groups: This type of enrollment entry requires intermediate or root certificates. 有关详细信息,请参阅使用 X.509 证书控制设备对预配服务的访问For more information, see Controlling device access to the provisioning service with X.509 certificates.

模拟设备Simulated devices

收集安全项目的过程如下所述,具体取决于你构建 SDK 的目的是使用 TPM 还是使用 X.509 证书对模拟设备进行认证:Depending on whether you built the SDK to use attestation for a simulated device using TPM or X.509 certificates, gathering the security artifacts is as follows:

  • 对于模拟 TPM 设备:For a simulated TPM device:

    1. 打开一个 Windows 命令提示符,导航到 azure-iot-sdk-c 子目录,然后运行 TPM 模拟器。Open a Windows Command Prompt, navigate to the azure-iot-sdk-c subdirectory, and run the TPM simulator. 该模拟器通过套接字在端口 2321 和 2322 上进行侦听。It 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 the following Quickstart.

      azure-iot-sdk-c 子目录运行以下命令,以启动模拟器:From the azure-iot-sdk-c subdirectory, run the following command to start the simulator:

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

      Note

      如果使用 Git Bash 命令 提示符执行此步骤,则需要将反斜杠更改为正斜杠,例如:./provisioning_client/deps/utpm/tools/tpm_simulator/Simulator.exeIf you use the Git Bash command prompt for this step, you'll need to change the backslashes to forward slashes, for example: ./provisioning_client/deps/utpm/tools/tpm_simulator/Simulator.exe.

    2. 使用 Visual Studio 打开在 cmake 文件夹中创建的名为 azure_iot_sdks.sln 的解决方案,然后在“生成”菜单上使用“生成解决方案”命令来生成它。Using Visual Studio, open the solution generated in the cmake folder named azure_iot_sdks.sln, and build it using the "Build solution" command on the "Build" menu.

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

    4. 使用“调试”菜单上的任一“启动”命令来运行此解决方案。Run the solution using either of the "Start" commands on the "Debug" menu. 输出窗口会显示 TPM 模拟器的“注册 ID” 和“认可密钥” ,这是进行设备登记和注册所需的。The output window displays the TPM simulator's Registration ID and the Endorsement Key, needed for device enrollment and registration. 复制这些值,供以后使用。Copy these values for use later. 可以关闭此窗口(包含注册 ID 和认可密钥),但让在步骤 1 中启动的 TPM 模拟器窗口保持运行状态。You can close this window (with Registration ID and Endorsement Key), but leave the TPM simulator window running that you started in step #1.

  • 对于模拟 X.509 设备:For a simulated X.509 device:

    1. 使用 Visual Studio 打开在 cmake 文件夹中创建的名为 azure_iot_sdks.sln 的解决方案,然后在“生成”菜单上使用“生成解决方案”命令来生成它。Using Visual Studio, open the solution generated in the cmake folder named azure_iot_sdks.sln, and build it using the "Build solution" command on the "Build" menu.

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

    3. 使用“调试”菜单上的任一“启动”命令来运行此解决方案。Run the solution using either of the "Start" commands on the "Debug" menu. 在输出窗口中,当系统提示时输入 i 完成单个注册。In the output window, enter i for individual enrollment when prompted. 输出窗口会显示在本地为模拟设备生成的 X.509 证书。The output window displays a locally generated X.509 certificate for your simulated device. 将输出(从 -----BEGIN CERTIFICATE----- 开始,到第一个 -----END CERTIFICATE----- 结束)复制到剪贴板,确保将这两行也包括进去。Copy to clipboard the output starting from -----BEGIN CERTIFICATE----- and ending at the first -----END CERTIFICATE-----, making sure to include both of these lines as well. 只需要使用输出窗口中的第一个证书。You only need the first certificate from the output window.

    4. 创建名为 X509testcert.pem 的文件,在所选文本编辑器中将其打开,然后将剪贴板内容复制到该文件中。Create a file named X509testcert.pem, open it in a text editor of your choice, and copy the clipboard contents to this file. 保存此文件,因为稍后需要用它来进行设备注册。Save the file as you will use it later for device enrollment. 注册软件在运行时使用自动预配期间使用的证书。When your registration software runs, it uses the same certificate during auto-provisioning.

在将设备注册到设备预配服务的过程中,这些安全项目是必需的。These security artifacts are required during enrollment your device to the Device Provisioning Service. 预配服务会等待设备启动并随后与其连接。The provisioning service waits for the device to boot and connect with it at any later point in time. 设备首次启动时,客户端 SDK 逻辑会与芯片(或模拟器)交互以提取设备中的安全项目,并验证是否已向设备预配服务注册。When your device boots for the first time, the client SDK logic interacts with your chip (or simulator) to extract the security artifacts from the device, and verifies registration with your Device Provisioning service.

创建设备注册软件Create the device registration software

最后一步是编写一个注册应用程序,以便使用设备预配服务客户端 SDK 将设备注册到 IoT 中心服务。The last step is to write a registration application that uses the Device Provisioning Service client SDK to register the device with the IoT Hub service.

Note

对于这一步,我们假定使用的是模拟设备,通过从工作站运行 SDK 示例注册应用程序的方式来完成。For this step we will assume the use of a simulated device, accomplished by running an SDK sample registration application from your workstation. 不过,如果生成需要部署到物理设备的注册应用程序,则适用的概念是相同的。However, the same concepts apply if you are building a registration application for deployment to a physical device.

  1. 在 Azure 门户中,选择设备预配服务的“概览”边栏选项卡,复制“ID 范围”值。 In the Azure portal, select the Overview blade for your Device Provisioning service and copy the ID Scope value. ID 范围由此服务生成,可保证唯一性 。The ID Scope is generated by the service and guarantees uniqueness. 它是不可变的,可用于唯一标识注册 ID。It is immutable and used to uniquely identify the registration IDs.

    从门户边栏选项卡中提取设备预配服务终结点信息

  2. 在计算机上的 Visual Studio 解决方案资源管理器中,导航到 Provision_Samples 文件夹。In the Visual Studio Solution Explorer on your machine, navigate to the folder Provision_Samples. 选择名为 prov_dev_client_sample 的示例项目,打开 prov_dev_client_sample.c 源文件。Select the sample project named prov_dev_client_sample and open the source file prov_dev_client_sample.c.

  3. 将步骤 1 中获得的“ID 范围”值分配 给 id_scope 变量(删除左侧的 /[ 和右侧的 /] 方括号):Assign the ID Scope value obtained in step #1, to the id_scope variable (removing the left/[ and right/] brackets):

    static const char* global_prov_uri = "global.azure-devices-provisioning.net";
    static const char* id_scope = "[ID Scope]";
    

    例如,IoT 中心客户端注册 API IoTHubClient_LL_CreateFromDeviceAuth 可以使用 global_prov_uri 变量通过指定的设备预配服务实例进行连接。For reference, the global_prov_uri variable, which allows the IoT Hub client registration API IoTHubClient_LL_CreateFromDeviceAuth to connect with the designated Device Provisioning Service instance.

  4. 在同一文件的 main() 函数中,注释/取消注释与设备的注册软件所用证明机制(TPM 或 X.509)相匹配的 hsm_type 变量:In the main() function in the same file, comment/uncomment the hsm_type variable that matches the attestation mechanism being used by your device's registration software (TPM or X.509):

    hsm_type = SECURE_DEVICE_TYPE_TPM;
    //hsm_type = SECURE_DEVICE_TYPE_X509;
    
  5. 保存所做的更改,然后从“生成”菜单中选择“生成解决方案”,以便重新生成 prov_dev_client_sample 示例。Save your changes and rebuild the prov_dev_client_sample sample by selecting "Build solution" from the "Build" menu.

  6. 右键单击 Provision_Samples 文件夹中的 prov_dev_client_sample 项目,然后选择“设置为启动项目”。 Right-click the prov_dev_client_sample project under the Provision_Samples folder, and select Set as Startup Project. 目前请勿运行示例应用程序。DO NOT run the sample application yet.

Important

目前请勿运行/启动设备!Do not run/start the device yet! 在启动设备之前,需先将设备注册到设备预配服务,以便完成此过程。You need to finish the process by enrolling the device with the Device Provisioning Service first, before starting the device. 下面的“后续步骤”部分会引导你阅读下一篇文章。The Next steps section below will guide you to the next article.

在注册过程中使用的 SDK API(仅供参考)SDK APIs used during registration (for reference only)

例如,此 SDK 提供下述可供应用程序在注册过程中使用的 API。For reference, the SDK provides the following APIs for your application to use during registration. 设备启动时,这些 API 可帮助设备连接设备预配服务并向其注册。These APIs help your device connect and register with the Device Provisioning Service when it boots up. 反过来,设备可以接收必要的信息,以便建立到 IoT 中心实例的连接:In return, your device receives the information required to establish a connection to your IoT Hub instance:

// Creates a Provisioning Client for communications with the Device Provisioning Client Service.  
PROV_DEVICE_LL_HANDLE Prov_Device_LL_Create(const char* uri, const char* scope_id, PROV_DEVICE_TRANSPORT_PROVIDER_FUNCTION protocol)

// Disposes of resources allocated by the provisioning Client.
void Prov_Device_LL_Destroy(PROV_DEVICE_LL_HANDLE handle)

// Asynchronous call initiates the registration of a device.
PROV_DEVICE_RESULT Prov_Device_LL_Register_Device(PROV_DEVICE_LL_HANDLE handle, PROV_DEVICE_CLIENT_REGISTER_DEVICE_CALLBACK register_callback, void* user_context, PROV_DEVICE_CLIENT_REGISTER_STATUS_CALLBACK reg_status_cb, void* status_user_ctext)

// Api to be called by user when work (registering device) can be done
void Prov_Device_LL_DoWork(PROV_DEVICE_LL_HANDLE handle)

// API sets a runtime option identified by parameter optionName to a value pointed to by value
PROV_DEVICE_RESULT Prov_Device_LL_SetOption(PROV_DEVICE_LL_HANDLE handle, const char* optionName, const void* value)

你可能还会发现,需要先后使用模拟设备和测试性服务安装程序来优化设备预配服务客户端注册应用程序。You may also find that you need to refine your Device Provisioning Service client registration application, using a simulated device at first, and a test service setup. 应用程序在测试环境中正常运行后,便可为特定设备生成此应用程序并将可执行文件复制到设备映像。Once your application is working in the test environment, you can build it for your specific device and copy the executable to your device image.

清理资源Clean up resources

目前,你可能正在门户中预配设备并运行 IoT 中心服务。At this point, you might have the Device Provisioning and IoT Hub services running in the portal. 若要放弃设备预配设置并且/或者将本教程系列的完成时间延后,建议将它们关闭,避免产生不必要的费用。If you wish to abandon the device provisioning setup, and/or delay completion of this tutorial series, we recommend shutting them down to avoid incurring unnecessary costs.

  1. 在 Azure 门户的左侧菜单中单击“所有资源”,然后选择设备预配服务 。From the left-hand menu in the Azure portal, click All resources and then select your Device Provisioning service. 在“所有资源”边栏选项卡的顶部单击“删除” 。At the top of the All resources blade, click Delete.
  2. 在 Azure 门户的左侧菜单中单击“所有资源”,然后选择 IoT 中心 。From the left-hand menu in the Azure portal, click All resources and then select your IoT hub. 在“所有资源”边栏选项卡的顶部单击“删除” 。At the top of the All resources blade, click Delete.

后续步骤Next steps

在本教程中,你已学习了如何执行以下操作:In this tutorial, you learned how to:

  • 生成特定于平台的设备预配服务客户端 SDKBuild platform-specific Device Provisioning Service Client SDK
  • 提取安全项目Extract the security artifacts
  • 创建设备注册软件Create the device registration software

前往下一教程,了解如何向 Azure IoT 中心设备预配服务注册设备以进行自动预配,从而将设备预配到 IoT 中心。Advance to the next tutorial to learn how to provision the device to your IoT hub by enrolling it to the Azure IoT Hub Device Provisioning Service for auto-provisioning.