快速入门:使用对称密钥预配模拟设备Quickstart: Provision a simulated device with symmetric keys

本快速入门介绍如何在 Windows 开发计算机上创建和运行设备模拟器。In this quickstart, you will learn how to create and run a device simulator on a Windows development machine. 你将配置此模拟设备,以使用对称密钥对设备预配服务实例进行身份验证,并将此模拟设备分配到 IoT 中心。You will configure this simulated device to use a symmetric key to authenticate with a Device Provisioning Service instance and be assigned to an IoT hub. 将使用 Azure IoT C SDK 中的示例代码来模拟启动预配的设备的启动序列。Sample code from the Azure IoT C SDK will be used to simulate a boot sequence for the device that initiates provisioning. 将根据预配服务实例的单个注册来识别该设备,然后将其分配到 IoT 中心。The device will be recognized based on an individual enrollment with a provisioning service instance and assigned to an IoT hub.

虽然本文演示了使用单个注册进行预配,但你也可以使用注册组。Although this article demonstrates provisioning with an individual enrollment, you can use enrollment groups. 使用注册组时有一些不同之处。There are some differences when using enrollment groups. 例如,必须将派生的设备密钥与设备的唯一注册 ID 一起使用。For example, you must use a derived device key with a unique registration ID for the device. 虽然对称密钥注册组不限于旧设备,但如何使用对称密钥证明预配旧设备提供了注册组示例。Although symmetric key enrollment groups are not limited to legacy devices, How to provision legacy devices using Symmetric key attestation provides an enrollment group example. 有关详细信息,请参阅对称密钥证明的组注册For more information, see Group Enrollments for Symmetric Key Attestation.

如果你不熟悉自动预配过程,请查看自动预配的概念If you're unfamiliar with the process of auto-provisioning, 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. 本快速入门需要你已创建设备预配服务实例。This quickstart requires you to have already created your Device Provisioning Service instance.

本文面向基于 Windows 的工作站。This article is oriented toward a Windows-based workstation. 但是,你也可以在 Linux 上执行过程。However, you can perform the procedures on Linux. 对于 Linux 示例,请参阅如何进行多租户预配For a Linux example, see How to provision for multitenancy.

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

先决条件Prerequisites

以下先决条件适用于 Windows 开发环境。The following prerequisites are for a Windows development environment. 对于 Linux 或 macOS,请参阅 SDK 文档的准备开发环境中的相应部分。For Linux or macOS, see the appropriate section in Prepare your development environment in the SDK documentation.

准备 Azure IoT C SDK 开发环境Prepare an Azure IoT C SDK development environment

在本部分,你将准备一个用于生成 Azure IoT C SDK 的开发环境。In this section, you will prepare a development environment used to build the Azure IoT C SDK.

SDK 包含模拟设备的示例代码。The SDK includes the sample code for a simulated device. 该模拟设备将尝试在设备启动顺序期间进行预配。This simulated device will attempt provisioning during the device's boot sequence.

  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.

    旧版本的 CMake 生成系统无法生成本文中使用的解决方案文件。Older versions of the CMake build system fail to generate the solution file used in this article. 请确保使用较新版本的 CMake。Make sure to use a newer version of CMake.

  2. 单击“标记” ,然后在 Azure IoT C SDK 的版本页上查找最新版本的标记名称。Click Tags and find the tag name for the latest release on the Release page of the Azure IoT C SDK.

  3. 打开命令提示符或 Git Bash shell。Open a command prompt or Git Bash shell. 运行以下命令以克隆最新版本的 Azure IoT C SDK GitHub 存储库。Run the following commands to clone the latest release of the Azure IoT C SDK GitHub repository. 使用在上一步中找到的标记作为 -b 参数的值:Use the tag you found in the previous step as the value for the -b parameter:

    git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
    cd azure-iot-sdk-c
    git submodule update --init
    

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

  4. 在 git 存储库的根目录中创建 cmake 子目录,并导航到该文件夹。Create a cmake subdirectory in the root directory of the git repository, and navigate to that folder. azure-iot-sdk-c 目录运行以下命令:Run the following commands from the azure-iot-sdk-c directory:

    mkdir cmake
    cd cmake
    
  5. 运行以下命令,生成特定于你的开发客户端平台的 SDK 版本。Run the following command, which builds a version of the SDK specific to your development client platform. 将在 cmake 目录中生成模拟设备的 Visual Studio 解决方案。A Visual Studio solution for the simulated device will be generated in the cmake directory.

    cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client: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 -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client: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
    

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

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

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

  3. 在“添加注册”面板中输入以下信息,然后按“保存”按钮 。In the Add Enrollment panel, enter the following information, and press the Save button.

    • 机制:选择“对称密钥”作为标识证明“机制” 。Mechanism: Select Symmetric Key as the identity attestation Mechanism.

    • 自动生成密钥:选中此框。Auto-generate keys: Check this box.

    • 注册 ID:输入注册 ID 以标识注册。Registration ID: Enter a registration ID to identify the enrollment. 仅使用小写字母数字和短划线(“-”)字符。Use only lowercase alphanumeric and dash ('-') characters. 例如,symm-key-device-007 。For example, symm-key-device-007.

    • IoT 中心设备 ID: 输入设备标识符。IoT Hub Device ID: Enter a device identifier. 例如:device-007 。For example, device-007.

      在门户中为对称密钥证明添加单个注册

  4. 保存注册后,将生成“主要密钥”和“辅助密钥”,并将其添加到注册条目 。Once you have saved your enrollment, the Primary Key and Secondary Key will be generated and added to the enrollment entry. 对称密钥设备注册会在“单独注册” 选项卡的“注册 ID” 列下显示为 symm-key-device-007 。Your symmetric key device enrollment appears as symm-key-device-007 under the Registration ID column in the Individual Enrollments tab.

    打开注册并复制生成的“主要密钥” 的值。Open the enrollment and copy the value of your generated Primary Key.

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

在本部分更新向设备预配服务实例发送设备启动序列的示例代码。In this section, update the sample code 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 note the ID Scope value.

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

  2. 在 Visual Studio 中,打开通过运行 CMake 生成的 azure_iot_sdks.sln 解决方案文件。In Visual Studio, open the azure_iot_sdks.sln solution file that was generated by running CMake. 解决方案文件应位于以下位置:The solution file should be in the following location:

    \azure-iot-sdk-c\cmake\azure_iot_sdks.sln
    

    如果该文件不是在 cmake 目录中生成的,请确保使用的是最新版本的 CMake 生成系统。If the file was not generated in your cmake directory, make sure you used a recent version of the CMake build system.

  3. 在 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.

  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_SYMMETRIC_KEY,如下所示:Make sure the hsm_type variable is set to SECURE_DEVICE_TYPE_SYMMETRIC_KEY as shown below:

    SECURE_DEVICE_TYPE hsm_type;
    //hsm_type = SECURE_DEVICE_TYPE_TPM;
    //hsm_type = SECURE_DEVICE_TYPE_X509;
    hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
    
  6. prov_dev_client_sample.c 中,找到已注释掉的对 prov_dev_set_symmetric_key_info() 的调用。Find the call to prov_dev_set_symmetric_key_info() in prov_dev_client_sample.c which is commented out.

    // Set the symmetric key if using they auth type
    //prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");
    

    取消对函数调用的注释,并将占位符值(包括尖括号)替换为注册 ID 和主键值。Uncomment the function call, and replace the placeholder values (including the angle brackets) with your registration ID and primary key values.

    // Set the symmetric key if using they auth type
    prov_dev_set_symmetric_key_info("symm-key-device-007", "your primary key here");
    

    保存文件。Save the file.

  7. 右键单击“prov_dev_client_sample”项目, 然后选择“设为启动项目”。 Right-click the prov_dev_client_sample project and select Set as Startup Project.

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

    以下输出是模拟设备成功启动并连接到要分配到 IoT 中心的预配服务实例的示例:The following output is an example of the simulated device successfully booting up, and connecting to the provisioning Service instance to be assigned to an IoT hub:

    Provisioning API Version: 1.2.8
    
    Registering Device
    
    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.cn, deviceId: device-007    
    Press enter key to exit:
    
  9. 在门户中,导航到模拟设备分配到的 IoT 中心,然后选择“IoT 设备”选项卡 。将模拟设备成功预配到中心以后,设备 ID 会显示在“IoT 设备” 边栏选项卡上,“状态”为“已启用” 。In the portal, navigate to the IoT hub your simulated device was assigned to and select the IoT devices tab. On successful provisioning of the simulated to the hub, its device ID appears on the IoT Devices blade, with STATUS as enabled. 你可能需要按顶部的“刷新”按钮 。You might need to press the Refresh button at the top.

    设备注册到 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. 在 Azure 门户的左侧菜单中选择“所有资源”,然后选择设备预配服务 。From the left-hand menu in the Azure portal, select All resources and then select your Device Provisioning service. 打开服务的“管理注册”,然后选择“个人注册”选项卡 。选中在本快速入门中注册的设备的“注册 ID”旁边的复选框,然后按窗格顶部的“删除”按钮 。Open Manage Enrollments for your service, and then select the Individual Enrollments tab. Select the check box next to the REGISTRATION ID of the device you enrolled in this quickstart, and press the Delete button at the top of the pane.
  3. 在 Azure 门户的左侧菜单中选择“所有资源”,然后选择 IoT 中心 。From the left-hand menu in the Azure portal, select All resources and then select your IoT hub. 打开中心的“IoT 设备”,选中在本快速入门中注册的设备的“设备 ID”旁边的复选框,然后按窗格顶部的“删除”按钮 。Open IoT devices for your hub, select the check box next to the DEVICE ID of the device you registered in this quickstart, and then press the Delete button at the top of the pane.

后续步骤Next steps

本快速入门介绍了如何在 Windows 计算机上创建模拟设备,以及如何在门户中通过 Azure IoT 中心设备预配服务使用对称密钥将其预配到 IoT 中心。In this quickstart, you've created a simulated device on your Windows machine and provisioned it to your IoT hub using Symmetric key with the Azure IoT Hub Device Provisioning Service on the portal. 若要了解如何以编程方式注册设备,请继续学习快速入门中关于 X.509 设备的编程注册部分的内容。To learn how to enroll your device programmatically, continue to the quickstart for programmatic enrollment of X.509 devices.