使用对称密钥证明创建和预配 IoT Edge 设备Create and provision an IoT Edge device using symmetric key attestation

可以使用设备预配服务自动预配 Azure IoT Edge 设备,就像预配未启用 Edge 的设备一样。Azure IoT Edge devices can be auto-provisioned using the Device Provisioning Service just like devices that are not edge-enabled. 如果你不熟悉自动预配过程,请在继续操作之前查看预配概述。If you're unfamiliar with the process of auto-provisioning, review the provisioning overview before continuing.

本文介绍如何通过以下步骤,在 IoT Edge 设备上使用对称密钥证明创建设备预配服务的单个注册:This article shows you how to create a Device Provisioning Service individual enrollment using symmetric key attestation on an IoT Edge device with the following steps:

  • 创建 IoT 中心设备预配服务 (DPS) 的实例。Create an instance of IoT Hub Device Provisioning Service (DPS).
  • 为设备创建个人注册。Create an individual enrollment for the device.
  • 安装 IoT Edge 运行时并连接到 IoT 中心。Install the IoT Edge runtime and connect to the IoT Hub.

对称密钥证明是一种通过设备预配服务实例对设备进行身份验证的简单方法。Symmetric key attestation is a simple approach to authenticating a device with a Device Provisioning Service instance. 此证明方法表示不熟悉设备预配或不具备严格安全要求的开发人员的“Hello world”体验。This attestation method represents a "Hello world" experience for developers who are new to device provisioning, or do not have strict security requirements. 使用 TPMX.509 证书的设备证明更加安全,且应该用于更严格的安全要求。Device attestation using a TPM or X.509 certificates is more secure, and should be used for more stringent security requirements.

先决条件Prerequisites

  • 一个有效的 IoT 中心An active IoT Hub
  • 一个物理设备或虚拟设备A physical or virtual device

设置 IoT 中心设备预配服务Set up the IoT Hub Device Provisioning Service

在 Azure 中创建 IoT 中心设备预配服务的新实例,并将其链接到 IoT 中心。Create a new instance of the IoT Hub Device Provisioning Service in Azure, and link it to your IoT hub. 可以遵照设置 IoT 中心 DPS 中的说明操作。You can follow the instructions in Set up the IoT Hub DPS.

运行设备预配服务后,从概述页复制“ID 范围”的值。 After you have the Device Provisioning Service running, copy the value of ID Scope from the overview page. 配置 IoT Edge 运行时时,需要使用此值。You use this value when you configure the IoT Edge runtime.

选择设备的唯一注册 IDChoose a unique registration ID for the device

必须定义唯一注册 ID 来标识每个设备。A unique registration ID must be defined to identify each device. 可以使用 MAC 地址、序列号或设备中的任何唯一信息。You can use the MAC address, serial number, or any unique information from the device.

在此示例中,我们使用 MAC 地址和序列号的组合,构成以下注册 ID 字符串:sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6In this example, we use a combination of a MAC address and serial number forming the following string for a registration ID: sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6.

为设备创建一个唯一注册 ID。Create a unique registration ID for your device. 有效字符为小写字母数字和短划线(“-”)。Valid characters are lowercase alphanumeric and dash ('-').

创建 DPS 注册Create a DPS enrollment

使用设备的注册 ID 在 DPS 中创建单个注册。Use your device's registration ID to create an individual enrollment in DPS.

在 DPS 中创建注册时,可以声明“初始设备孪生状态”。 When you create an enrollment in DPS, 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 you need in your solution, like region, environment, location, or device type. 这些标记用于创建自动部署These tags are used to create automatic deployments.

提示

也可以在使用对称密钥证明时创建组注册,这与创建单个注册时的考虑因素相同。Group enrollments are also possible when using symmetric key attestation and involve the same decisions as individual enrollments.

  1. Azure 门户中,导航到 IoT 中心设备预配服务的实例。In the Azure portal, navigate to your instance of IoT Hub Device Provisioning Service.

  2. 在“设置”下,选择“管理注册”。 Under Settings, select Manage enrollments.

  3. 选择“添加个人注册”,然后完成以下步骤以配置注册: Select Add individual enrollment then complete the following steps to configure the enrollment:

    1. 对于“机制”,请选择“对称密钥”。 For Mechanism, select Symmetric Key.

    2. 选中“自动生成密钥”复选框。 Select the Auto-generate keys check box.

    3. 提供为设备创建的“注册 ID”。 Provide the Registration ID that you created for your device.

    4. 根据需要,为设备提供“IoT 中心设备 ID”。 Provide an IoT Hub Device ID for your device if you'd like. 可以使用设备 ID 将单个设备指定为模块部署的目标。You can use device IDs to target an individual device for module deployment. 如果未提供设备 ID,则会使用注册 ID。If you don't provide a device ID, the registration ID is used.

    5. 选择“True”,声明该注册适用于 IoT Edge 设备。 Select True to declare that the enrollment is for an IoT Edge device. 对于组注册,所有设备必须是 IoT Edge 设备,或者都不是 IoT Edge 设备。For a group enrollment, all devices must be IoT Edge devices or none of them can be.

    提示

    在 Azure CLI 中,可以创建注册注册组,并使用“支持 Edge” 标志来指定某个设备或设备组是 IoT Edge 设备。In the Azure CLI, you can create an enrollment or an enrollment group and use the edge-enabled flag to specify that a device, or group of devices, is an IoT Edge device.

    1. 接受设备预配服务分配策略中有关 如何将设备分配到中心 的默认值,或选择特定于此注册的其他值。Accept the default value from the Device Provisioning Service's allocation policy for how you want to assign devices to hubs or choose a different value that is specific to this enrollment.

    2. 选择要将设备连接到的链接“IoT 中心”。 Choose the linked IoT Hub that you want to connect your device to. 可以选择多个中心,设备将根据所选的分配策略分配到其中的一个中心。You can choose multiple hubs, and the device will be assigned to one of them according to the selected allocation policy.

    3. 选择 在首次预配后,重新预配设备请求时如何处理设备数据Choose how you want device data to be handled on re-provisioning when devices request provisioning after the first time.

    4. 根据需要,将标记值添加到“初始设备孪生状态”。 Add a tag value to the Initial Device Twin State if you'd like. 可以使用标记将设备组指定为模块部署的目标。You can use tags to target groups of devices for module deployment. 例如:For example:

      {
         "tags": {
            "environment": "test"
         },
         "properties": {
            "desired": {}
         }
      }
      
    5. 确保“启用项”设置为“启用”。 Ensure Enable entry is set to Enable.

    6. 选择“保存” 。Select Save.

既然此设备已存在注册,IoT Edge 运行时在安装期间可以自动预配设备。Now that an enrollment exists for this device, the IoT Edge runtime can automatically provision the device during installation. 在安装 IoT Edge 运行时,或者要创建用于组注册的设备密钥时,请确保复制注册的 主密钥 值以供使用。Be sure to copy your enrollment's Primary Key value to use when installing the IoT Edge runtime, or if you're going to be creating device keys for use with a group enrollment.

派生一个设备密钥Derive a device key

备注

仅当使用组注册时,才需要此部分。This section is required only if using a group enrollment.

每个设备将使用其派生的设备密钥和唯一注册 ID,于预配期间在注册中执行对称密钥证明。Each device uses its derived device key with your unique registration ID to perform symmetric key attestation with the enrollment during provisioning. 若要生成设备密钥,请使用从 DPS 注册复制的密钥计算设备的唯一注册 ID 的 HMAC-SHA256,并将结果转换为 Base64 格式。To generate the device key, use the key you copied from your DPS enrollment to compute an HMAC-SHA256 of the unique registration ID for the device and convert the result into Base64 format.

不要在设备代码中包含注册的主密钥或辅助密钥。Do not include your enrollment's primary or secondary key in your device code.

Linux 工作站Linux workstations

如果使用的是 Linux 工作站,可以使用 openssl 生成派生的设备密钥,如以下示例中所示。If you are using a Linux workstation, you can use openssl to generate your derived device key as shown in the following example.

将“键” 值替换为前面记录的“主键” 。Replace the value of KEY with the Primary Key you noted earlier.

请将 REG_ID 值替换为设备的注册 ID。Replace the value of REG_ID with your device's registration ID.

KEY=8isrFI1sGsIlvvFSSFRiMfCNzv21fjbE/+ah/lSh3lF8e2YG1Te7w1KpZhJFFXJrqYKi9yegxkqIChbqOS9Egw==
REG_ID=sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6

keybytes=$(echo $KEY | base64 --decode | xxd -p -u -c 1000)
echo -n $REG_ID | openssl sha256 -mac HMAC -macopt hexkey:$keybytes -binary | base64
Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=

基于 Windows 的工作站Windows-based workstations

如果使用的是基于 Windows 的工作站,可以使用 PowerShell 生成派生的设备密钥,如以下示例中所示。If you are using a Windows-based workstation, you can use PowerShell to generate your derived device key as shown in the following example.

将“键” 值替换为前面记录的“主键” 。Replace the value of KEY with the Primary Key you noted earlier.

请将 REG_ID 值替换为设备的注册 ID。Replace the value of REG_ID with your device's registration ID.

$KEY='8isrFI1sGsIlvvFSSFRiMfCNzv21fjbE/+ah/lSh3lF8e2YG1Te7w1KpZhJFFXJrqYKi9yegxkqIChbqOS9Egw=='
$REG_ID='sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6'

$hmacsha256 = New-Object System.Security.Cryptography.HMACSHA256
$hmacsha256.key = [Convert]::FromBase64String($KEY)
$sig = $hmacsha256.ComputeHash([Text.Encoding]::ASCII.GetBytes($REG_ID))
$derivedkey = [Convert]::ToBase64String($sig)
echo "`n$derivedkey`n"
Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=

安装 IoT Edge 运行时Install the IoT Edge runtime

IoT Edge 运行时部署在所有 IoT Edge 设备上。The IoT Edge runtime is deployed on all IoT Edge devices. 该运行时的组件在容器中运行,允许你将其他容器部署到设备,以便在边缘上运行代码。Its components run in containers, and allow you to deploy additional containers to the device so that you can run code at the edge.

按照安装 Azure IoT Edge 运行时中的步骤操作,然后返回到本文来预配设备。Follow the steps in Install the Azure IoT Edge runtime, then return to this article to provision the device.

用预配信息配置设备Configure the device with provisioning information

在设备上安装运行时后,请借助它用于连接到设备预配服务和 IoT 中心的信息来配置设备。Once 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.

准备好以下信息:Have the following information ready:

  • DPS 的“ID 范围”值 The DPS ID Scope value
  • 为设备创建的“注册 ID” The device Registration ID you created
  • 从 DPS 注册复制的 主密钥The Primary Key you copied from the DPS enrollment

提示

对于组注册,需要每个设备的派生密钥,而不是 DPS 注册密钥。For group enrollments, you need each device's derived key rather than the DPS enrollment key.

Linux 设备Linux device

  1. 在 IoT Edge 设备上打开配置文件。Open the configuration file on the IoT Edge device.

    sudo nano /etc/iotedge/config.yaml
    
  2. 找到该文件的预配配置部分。Find the provisioning configurations section of the file. 取消注释 DPS 对称密钥预配的行,并确保注释掉任何其他预配行。Uncomment the lines for DPS symmetric key provisioning, and make sure any other provisioning lines are commented out.

    provisioning: 行前面应无空格,并且嵌套项应该缩进两个空格。The provisioning: line should have no preceding whitespace, and nested items should be indented by two spaces.

    # DPS TPM provisioning configuration
    provisioning:
      source: "dps"
      global_endpoint: "https://global.azure-devices-provisioning.cn"
      scope_id: "<SCOPE_ID>"
      attestation:
        method: "symmetric_key"
        registration_id: "<REGISTRATION_ID>"
        symmetric_key: "<SYMMETRIC_KEY>"
    
  3. scope_idregistration_idsymmetric_key 的值更新为你的 DPS 和设备信息。Update the values of scope_id, registration_id, and symmetric_key with your DPS and device information.

  4. 重启 IoT Edge 运行时,使之拾取你在设备上所做的所有配置更改。Restart the IoT Edge runtime so that it picks up all the configuration changes that you made on the device.

    sudo systemctl restart iotedge
    

Windows 设备Windows device

  1. 在管理员模式下打开 PowerShell 窗口。Open a PowerShell window in administrator mode. 在安装 IoT Edge 而不是 PowerShell (x86) 时,请确保使用 PowerShell 的 AMD64 会话。Be sure to use an AMD64 session of PowerShell when installing IoT Edge, not PowerShell (x86).

  2. Initialize-IoTEdge 命令在计算机上配置 IoT Edge 运行时。The Initialize-IoTEdge command configures the IoT Edge runtime on your machine. 该命令默认为使用 Windows 容器手动预配,因此使用 -DpsSymmetricKey 标志借助对称密钥身份验证来使用自动预配。The command defaults to manual provisioning with Windows containers, so use the -DpsSymmetricKey flag to use automatic provisioning with symmetric key authentication.

    请将 {scope_id}{registration_id}{symmetric_key} 的占位符值替换为前面收集的数据。Replace the placeholder values for {scope_id}, {registration_id}, and {symmetric_key} with the data you collected earlier.

    如果是在 Windows 上使用 Linux 容器,则添加 -ContainerOs Linux 参数。Add the -ContainerOs Linux parameter if you're using Linux containers on Windows.

    . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
    Initialize-IoTEdge -DpsSymmetricKey -ScopeId {scope ID} -RegistrationId {registration ID} -SymmetricKey {symmetric key}
    

验证是否成功安装Verify successful installation

如果运行时成功启动,则可以进入 IoT 中心,开始将 IoT Edge 模块部署到你的设备。If the runtime started successfully, you can 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.

Linux 设备Linux device

检查 IoT Edge 服务的状态。Check the status of the IoT Edge service.

systemctl status iotedge

检查服务日志。Examine service logs.

journalctl -u iotedge --no-pager --no-full

列出正在运行的模块。List running modules.

iotedge list

Windows 设备Windows device

检查 IoT Edge 服务的状态。Check the status of the IoT Edge service.

Get-Service iotedge

检查服务日志。Examine service logs.

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

列出正在运行的模块。List running modules.

iotedge list

可以验证是否使用了在设备预配服务中创建的个人注册。You can verify that the individual enrollment that you created in Device Provisioning Service was used. 在 Azure 门户中导航到设备预配服务实例。Navigate to your Device Provisioning Service instance in the Azure portal. 打开创建的个人注册的注册详细信息。Open the enrollment details for the individual enrollment that you created. 注意注册状态是否为“已分配”并且设备 ID 已列出。 Notice that the status of the enrollment is assigned and the device ID is listed.

后续步骤Next steps

使用设备预配服务注册过程可以在预配新设备的同时,设置设备 ID 和设备孪生标记。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 using automatic device management. 了解如何使用 Azure 门户大规模部署和监视 IoT Edge 模块,或使用 Azure CLI 执行此操作。Learn how to Deploy and monitor IoT Edge modules at scale using the Azure portal or using Azure CLI.