快速入门:使用适用于 IoT 中心设备预配服务的 C 设备 SDK 创建和预配 X.509 设备Quickstart: Create and provision an X.509 device using C# device SDK for IoT Hub Device Provisioning Service

这些步骤显示了如何使用 C# 的 Azure IoT 示例中的设备代码来预配 X.509 设备。These steps show you how to use device code from the Azure IoT Samples for C# to provision an X.509 device. 在本文中,你将在开发计算机上运行设备示例代码,以使用设备预配服务连接到 IoT 中心。In this article, you will run device sample code on your development machine to connect to an IoT Hub using the Device Provisioning Service.

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

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

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

备注

初始的设备孪生状态配置仅在 IoT 中心的标准层中提供。The initial device twin state configuration is available only in the standard tier of IoT Hub. 有关基本和标准 IoT 中心层的详细信息,请参阅如何选择合适的 IoT 中心层For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

准备开发环境Prepare the development environment

  1. 确保在计算机上安装 git 并将其添加到可供命令窗口访问的环境变量。Make sure git is installed on your machine and is added to the environment variables accessible to the command window. 请参阅软件自由保护组织提供的 Git 客户端工具,了解要安装的最新版 git 工具,其中包括 Git Bash,这是一个命令行应用,可以用来与本地 Git 存储库交互。See Software Freedom Conservancy's Git client tools for the latest version of git tools to install, which includes the Git Bash, the command-line app that you can use to interact with your local Git repository.

  2. 打开命令提示符或 Git Bash。Open a command prompt or Git Bash. 克隆用于 C# GitHub 存储库的 Azure IoT 示例:Clone the Azure IoT Samples for C# GitHub repo:

    git clone https://github.com/Azure-Samples/azure-iot-samples-csharp.git
    
  3. 确保已在计算机上安装 .NET Core 3.0.0 SDK 或更高版本Make sure you have the .NET Core 3.0.0 SDK or later installed on your machine. 可使用以下命令来检查你的版本。You can use the following command to check your version.

    dotnet --info
    

创建自签名的 X.509 设备证书Create a self-signed X.509 device certificate

在本部分中,你将使用 iothubx509device1 作为使用者共用名称来创建自签名 X.509 测试证书。In this section you, will create a self-signed X.509 test certificate using iothubx509device1 as the subject common name. 请务必记住以下几点:It is important to keep in mind the following points:

  • 自签名证书仅用于测试,不应在生产环境中使用。Self-signed certificates are for testing only, and should not be used in production.
  • 自签名证书的默认过期日期为一年。The default expiration date for a self-signed certificate is one year.
  • IoT 设备的设备 ID 将是证书上的使用者共用名称。The device ID of the IoT device will be the subject common name on the certificate. 确保使用符合设备 ID 字符串要求的使用者名称。Make sure to use a subject name that complies with the Device ID string requirements.

你将使用来自 X509Sample 的示例代码创建要与设备的个人注册项一起使用的证书。You will use sample code from the X509Sample to create the certificate to be used with the individual enrollment entry for the device.

  1. 在 PowerShell 提示符处,将目录更改为 X.509 设备预配示例的项目目录。In a PowerShell prompt, change directories to the project directory for the X.509 device provisioning sample.

    cd .\azure-iot-samples-csharp\provisioning\Samples\device\X509Sample
    
  2. 示例代码设置为使用在受密码保护的 PKCS12 格式文件 (certificate.pfx) 中存储的 X.509 证书。The sample code is set up to use X.509 certificates stored within a password-protected PKCS12 formatted file (certificate.pfx). 另外,还需要一个公钥证书文件 (certificate.cer),用于在本快速入门的后面部分创建单个注册。Additionally, you need a public key certificate file (certificate.cer) to create an individual enrollment later in this quickstart. 若要生成自签名证书及其关联的 .cer 和 .pfx 文件,请运行以下命令:To generate the self-signed certificate and its associated .cer and .pfx files, run the following command:

    PS D:\azure-iot-samples-csharp\provisioning\Samples\device\X509Sample> .\GenerateTestCertificate.ps1 iothubx509device1
    
  3. 脚本会提示输入 PFX 密码。The script prompts you for a PFX password. 请记住此密码,你稍后在运行示例时必须使用它。Remember this password, you must use it later again when you run the sample. 可运行 certutil 来转储证书并验证使用者名称。You can run certutil to dump the certificate and verify the subject name.

    PS D:\azure-iot-samples-csharp\provisioning\Samples\device\X509Sample> certutil .\certificate.pfx
    Enter PFX password:
    ================ Certificate 0 ================
    ================ Begin Nesting Level 1 ================
    Element 0:
    Serial Number: 7b4a0e2af6f40eae4d91b3b7ff05a4ce
    Issuer: CN=iothubx509device1, O=TEST, C=US
     NotBefore: 2/1/2021 6:18 PM
     NotAfter: 2/1/2022 6:28 PM
    Subject: CN=iothubx509device1, O=TEST, C=US
    Signature matches Public Key
    Root Certificate: Subject matches Issuer
    Cert Hash(sha1): e3eb7b7cc1e2b601486bf8a733887a54cdab8ed6
    ----------------  End Nesting Level 1  ----------------
      Provider = Microsoft Strong Cryptographic Provider
    Signature test passed
    CertUtil: -dump command completed successfully.    
    

为设备创建个人注册项Create an individual enrollment entry for the device

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

  2. 在“设备预配服务”菜单中,选择“管理注册”。From the Device Provisioning Service menu, select Manage enrollments. 选择“个人注册”选项卡,然后选择顶部的“添加个人注册”按钮 。Select Individual Enrollments tab and select the Add individual enrollment button at the top.

  3. 在“添加注册”面板中,输入以下信息:In the Add Enrollment panel, enter the following information:

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

    • 在“主要证书 .pem 或 .cer 文件”下,选择“选择文件”选择在前述步骤中创建的证书文件 certificate.cer 。Under the Primary certificate .pem or .cer file, choose Select a file to select the certificate file certificate.cer created in the previous steps.

    • 将“设备 ID”保留为空。 Leave Device ID blank. 对设备进行预配时,其设备 ID 将设置为 X.509 证书 iothubx509device1 中的公用名称 (CN)。Your device will be provisioned with its device ID set to the common name (CN) in the X.509 certificate, iothubx509device1. 此共用名称也将是用于单个注册项的注册 ID 的名称。This common name will also be the name used for the registration ID for the individual enrollment entry.

    • (可选)可以提供以下信息:Optionally, you may provide the following information:

      • 选择与预配服务链接的 IoT 中心。Select an IoT hub linked with your provisioning service.
      • 使用设备所需的初始配置更新“初始设备孪生状态” 。Update the Initial device twin state with the desired initial configuration for the device.
    • 完成后,按“保存”按钮。Once complete, press the Save button.

      在门户中为 X.509 证明添加单个注册Add individual enrollment for X.509 attestation in the portal

    成功注册以后,X.509 注册项会在“单个注册”选项卡的“注册 ID”栏下显示为 iothubx509device1On successful enrollment, your X.509 enrollment entry appears as iothubx509device1 under the Registration ID column in the Individual Enrollments tab.

预配设备Provision the device

  1. 在预配服务的“概览”边栏选项卡中,记下“ID 范围”的值。 From the Overview blade for your provisioning service, note the ID Scope value.

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

  2. 键入以下命令,生成并运行 X.509 设备预配示例。Type the following command to build and run the X.509 device provisioning sample. <IDScope> 值替换为预配服务的 ID 范围。Replace the <IDScope> value with the ID Scope for your provisioning service.

    证书文件将默认为 ./certificate.pfx,还将提示输入 .pfx 密码。The certificate file will default to ./certificate.pfx and prompt for the .pfx password.

    dotnet run -- -s <IDScope>
    

    如果要将所有内容都作为参数传递,可采用以下示例格式。If you want to pass everything as a parameter, you can use the following example format.

    dotnet run -- -s 0ne00000A0A -c certificate.pfx -p 1234
    
  3. 设备将连接到 DPS 并分配给 IoT 中心。The device will connect to DPS and be assigned to an IoT Hub. 设备还将向中心发送遥测消息。The device will additionally send a telemetry message to the hub.

    Loading the certificate...
    Found certificate: 10952E59D13A3E388F88E534444484F52CD3D9E4 CN=iothubx509device1, O=TEST, C=US; PrivateKey: True
    Using certificate 10952E59D13A3E388F88E534444484F52CD3D9E4 CN=iothubx509device1, O=TEST, C=US
    Initializing the device provisioning client...
    Initialized for registration Id iothubx509device1.
    Registering with the device provisioning service...
    Registration status: Assigned.
    Device iothubx509device2 registered to sample-iot-hub1.azure-devices.net.
    Creating X509 authentication for IoT Hub...
    Testing the provisioned device with IoT Hub...
    Sending a telemetry message...
    Finished.
    
  4. 验证设备是否已预配。Verify that the device has been provisioned. 将设备成功预配到与预配服务链接的 IoT 中心后,该中心的“IoT 设备”边栏选项卡上会显示设备 ID。On successful provisioning of the device to the IoT hub linked with your provisioning service, the device ID appears on the hub's IoT devices blade.

    设备注册到 IoT 中心

    如果从设备的注册项中的默认值更改了“初始设备孪生状态”,则它会从中心拉取所需的孪生状态,并执行相应的操作。If you changed the initial device twin state from the default value in the enrollment entry for your device, it can pull the desired twin state from the hub and act accordingly. 有关详细信息,请参阅了解并在 IoT 中心内使用设备孪生For more information, see Understand and use device twins in IoT Hub

清理资源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, select All resources and then select your Device Provisioning service. 在“概述”边栏选项卡顶部,按窗格顶部的“删除” 。At the top of the Overview blade, press Delete at the top of the pane.
  4. 在 Azure 门户的左侧菜单中选择“所有资源”,然后选择 IoT 中心 。From the left-hand menu in the Azure portal, select All resources and then select your IoT hub. 在“概述”边栏选项卡顶部,按窗格顶部的“删除” 。At the top of the Overview blade, press Delete at the top of the pane.

后续步骤Next steps

在此快速入门中,你使用 Azure IoT 中心设备预配服务将 X.509 设备预配到了 IoT 中心。In this quickstart, you provisioned an X.509 device to your IoT hub using the Azure IoT Hub Device Provisioning Service. 若要了解如何以编程方式注册 X.509 设备,请继续阅读快速入门中关于 X.509 设备的编程注册内容。To learn how to enroll your X.509 device programmatically, continue to the quickstart for programmatic enrollment of X.509 devices.