创建演示证书用于测试 IoT Edge 设备功能

项目
08/12/2024

适用于： IoT Edge 1.5 IoT Edge 1.4

重要

IoT Edge 1.5 LTS 和 IoT Edge 1.4 LTS 是受支持的版本。 IoT Edge 1.4 LTS 的生命周期结束日期为 2024 年 11 月 12 日。如果你使用的是较低的版本，请参阅更新 IoT Edge。

IoT Edge 设备需要使用证书来保护运行时、模块和任何下游设备之间的通信。如果你没有可创建所需证书的证书颁发机构，可以在测试环境中使用演示证书来试用 IoT Edge 功能。本文介绍 IoT Edge 提供用于测试的证书生成脚本的功能。

警告

这些证书将在 30 天后过期，不应在任何生产方案中使用。

可以在任何计算机上创建证书，然后将其复制到 IoT Edge 设备，或直接在 IoT Edge 设备上生成证书。

先决条件

装有 Git 的开发计算机。

下载测试证书脚本并设置工作目录

GitHub 上的 IoT Edge 存储库包含可用于创建演示证书的证书生成脚本。本部分说明如何准备好可在 Windows 或 Linux 计算机上运行的脚本。

Windows
Linux

若要在 Windows 设备上创建演示证书，需要安装 OpenSSL，然后克隆生成脚本，并将其设置为在 PowerShell 中本地运行。

安装 OpenSSL

在用于生成证书的计算机上安装 OpenSSL for Windows。如果已在 Windows 设备上安装 OpenSSL，请确保 PATH 环境变量中包含 openssl.exe。

可通过多种方式安装 OpenSSL，包括以下选项：

更轻松： 下载并安装任何第三方 OpenSSL 二进制文件，例如从 SourceForge 上的 OpenSSL 下载并安装。将 openssl.exe 的完整路径添加到 PATH 环境变量。
推荐： 在计算机上下载 OpenSSL 源代码并自行生成二进制文件，或者通过 vcpkg 生成。下面列出的说明使用 vcpkg 下载源代码，并在 Windows 计算机上编译和安装 OpenSSL，所用的步骤都很简单。
1. 导航到要安装 vcpkg 的目录。按照说明下载并安装 vcpkg。
2. 安装 vcpkg 后，在 PowerShell 提示符下运行以下命令以安装适用于 Windows x64 的 OpenSSL 包。此安装通常需要大约 5 分钟才能完成。
```
.\vcpkg install openssl:x64-windows
```
3. 将 <vcpkg path>\installed\x64-windows\tools\openssl 添加到 PATH 环境变量，以便可以调用 openssl.exe 文件。

在 PowerShell 中准备脚本

Azure IoT Edge Git 存储库包含可用于生成测试证书的脚本。在本部分，你将克隆 IoT Edge 存储库并执行脚本。

在管理员模式下打开 PowerShell 窗口。
克隆 IoT Edge Git 存储库，其中包含用于生成演示证书的脚本。使用 git clone 命令或下载 ZIP。
```
git clone https://github.com/Azure/iotedge.git
```
创建要在其中工作并复制证书脚本的目录。所有证书和密钥文件都将在此目录中创建。
```
mkdir wrkdir
cd .\wrkdir\
cp ..\iotedge\tools\CACertificates\*.cnf .
cp ..\iotedge\tools\CACertificates\ca-certs.ps1 .
```
如果下载了 ZIP 格式的存储库，则文件夹名称为 iotedge-master，路径的剩余部分相同。

启用 PowerShell 以运行脚本。

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

将脚本使用的函数放入 PowerShell 全局命名空间中。
```
. .\ca-certs.ps1
```
PowerShell 窗口中会显示一条警告，指出此脚本生成的证书仅用于测试目的，不应在生产方案中使用。
验证 OpenSSL 是否已正确安装，并确保现有的证书不会发生名称冲突。如果出现问题，脚本输出应会说明如何在系统上修复这些问题。
```
Test-CACertsPrerequisites
```

若要在 Linux 设备上创建演示证书，需要克隆生成脚本并将其设置为在 bash 中本地运行。

克隆 IoT Edge Git 存储库，其中包含用于生成演示证书的脚本。
```
git clone https://github.com/Azure/iotedge.git
```

创建要在其中工作并复制证书脚本的目录。所有证书和密钥文件都将在此目录中创建。

mkdir wrkdir
cd wrkdir
cp ../iotedge/tools/CACertificates/*.cnf .
cp ../iotedge/tools/CACertificates/certGen.sh .

创建根 CA 证书

运行此脚本以生成本文中每个步骤所需的根 CA。

根 CA 证书用于生成所有其他演示证书来测试 IoT Edge 方案。可以保持使用同一个根 CA 证书来为多个 IoT Edge 设备或下游设备生成演示证书。

如果工作文件夹中已包含一个根 CA 证书，请不要创建新的根 CA 证书。新根 CA 证书将覆盖旧证书，基于旧证书生成的任何下游证书将停止工作。如果需要多个根 CA 证书，请务必在单独的文件夹中管理这些证书。

Windows
Linux

导航到在其中放置了证书生成脚本的工作目录 wrkdir。
创建根 CA 证书，并使用它来签署一个中间证书。证书全部放在工作目录中。
```
New-CACertsCertChain rsa
```
此脚本命令将创建多个证书和密钥文件，但当文章中提到根 CA 证书时，请使用以下文件：

certs\azure-iot-test-only.root.ca.cert.pem

导航到在其中放置了证书生成脚本的工作目录 wrkdir。
创建根 CA 证书和一个中间证书。
```
./certGen.sh create_root_and_intermediate
```
此脚本命令将创建多个证书和密钥文件，但当文章中提到根 CA 证书时，请使用以下文件：

certs/azure-iot-test-only.root.ca.cert.pem

需要此证书，然后才能为 IoT Edge 设备和下游设备创建更多证书，如以下部分所述。

为 IoT Edge 设备创建标识证书

如果选择使用 X.509 证书身份验证，IoT Edge 设备标识证书将用于预配 IoT Edge 设备。如果使用对称密钥对 IoT 中心或 DPS 进行身份验证，则不需要这些证书，可以跳过此部分。

无论使用手动预配还是通过 Azure IoT 中心设备预配服务 (DPS) 进行自动预配，这些证书都有效。

设备标识证书位于 IoT Edge 设备配置文件的 Provisioning 节。

Windows
Linux

导航到包含证书生成脚本和根 CA 证书的工作目录 wrkdir。
使用以下命令创建 IoT Edge 设备标识证书和私钥：
```
New-CACertsEdgeDeviceIdentity "<device-id>"
```
传递给此命令的名称将是 IoT 中心的 IoT Edge 设备的设备 ID。

新的设备标识命令会创建多个证书和密钥文件：

类型	文件	说明
设备标识证书	`certs\iot-edge-device-identity-<device-id>.cert.pem`	由前面生成的中间证书签名。仅包含标识证书。在配置文件中指定，以便进行 DPS 单个注册或 IoT 中心预配。
完整链证书	`certs\iot-edge-device-identity-<device-id>-full-chain.cert.pem`	包含完整证书链，其中有中间证书。在配置文件中指定，以便 IoT Edge 将其提供给 DPS 进行组注册预配。
私钥	`private\iot-edge-device-identity-<device-id>.key.pem`	与设备标识证书关联的私钥。只要对 DPS 或 IoT 中心使用某种证书身份验证（指纹或 CA），就应在配置文件中指定。

导航到包含证书生成脚本和根 CA 证书的工作目录 wrkdir。
使用以下命令创建 IoT Edge 设备标识证书和私钥：
```
./certGen.sh create_edge_device_identity_certificate "<device-id>"
```
传递给此命令的名称将是 IoT 中心的 IoT Edge 设备的设备 ID。

此脚本会创建多个证书和密钥文件，其中包括在 DPS 中创建单个注册以及安装 IoT Edge 运行时时会使用的三个证书和密钥文件：

类型	文件	说明
设备标识证书	`certs/iot-edge-device-identity-<device-id>.cert.pem`	由前面生成的中间证书签名。仅包含标识证书。在配置文件中指定，以便进行 DPS 单个注册或 IoT 中心预配。
完整链证书	`certs/iot-edge-device-identity-<device-id>-full-chain.cert.pem`	包含完整证书链，其中有中间证书。在配置文件中指定，以便 IoT Edge 将其提供给 DPS 进行组注册预配。
私钥	`private/iot-edge-device-identity-<device-id>.key.pem`	与设备标识证书关联的私钥。只要对 DPS 或 IoT 中心使用某种证书身份验证（指纹或 CA），就应在配置文件中指定。

创建 Edge CA 证书

这些证书对于网关方案是必需的，因为 Edge CA 证书是 IoT Edge 设备向下游设备验证其身份的方式。如果不将任何下游设备连接到 IoT Edge，则可以跳过此部分。

Edge CA 证书还负责为设备上运行的模块创建证书，但如果未配置 Edge CA，IoT Edge 运行时可以创建临时证书。边缘 CA 证书会进入 IoT Edge 设备上的 config.toml 文件的“Edge CA”节中。有关详细信息，请参阅了解 Azure IoT Edge 如何使用证书。

Windows
Linux

导航到包含证书生成脚本和根 CA 证书的工作目录 wrkdir。
使用以下命令创建 IoT Edge CA 证书和私钥。请提供 CA 证书的名称。传递给 New-CACertsEdgeDevice 命令的名称不应与配置文件中的 hostname 参数或 IoT 中心的设备 ID 相同。
```
New-CACertsEdgeDevice "<CA cert name>"
```
此命令将创建多个证书和密钥文件。以下证书和密钥对需要复制到 IoT Edge 设备并在配置文件中引用：
- certs\iot-edge-device-ca-<CA cert name>-full-chain.cert.pem
- private\iot-edge-device-ca-<CA cert name>.key.pem

导航到包含证书生成脚本和根 CA 证书的工作目录。
使用以下命令创建 IoT Edge CA 证书和私钥。请提供 CA 证书的名称。传递给 create_edge_device_ca_certificate 命令的名称不应与配置文件中的 hostname 参数或 IoT 中心的设备 ID 相同。
```
./certGen.sh create_edge_device_ca_certificate "<CA cert name>"
```
此脚本命令将创建多个证书和密钥文件。以下证书和密钥对需要复制到 IoT Edge 设备并在配置文件中引用：
- certs/iot-edge-device-ca-<CA cert name>-full-chain.cert.pem
- private/iot-edge-device-ca-<CA cert name>.key.pem

创建下游设备证书

这些证书是为网关方案设置下游 IoT 设备所需的，需要将 X.509 身份验证与 IoT 中心或 DPS 配合使用。如果你要使用对称密钥身份验证，则无需为下游设备创建证书，可以跳过此部分。

可通过两种方式使用 X.509 证书对 IoT 设备进行身份验证：使用自签名证书，或使用证书颁发机构 (CA) 签名的证书。

对于 X.509 自签名身份验证（有时称为指纹身份验证），需要创建新证书并将其放在 IoT 设备上。这些证书包含一个指纹，你可以与 IoT 中心共享该指纹以完成身份验证。
对于 X.509 证书颁发机构 (CA) 签名的身份验证，需要在 IoT 中心或 DPS 中注册一个用来为 IoT 设备证书签名的根 CA 证书。使用由根 CA 证书或其任何中间证书颁发的证书的任何设备都可以进行身份验证，前提是设备提供完整链。

证书生成脚本可帮助你生成演示证书，以测试上述任一身份验证方案。

自签名证书

使用自签名证书对 IoT 设备进行身份验证时，需要基于解决方案的根 CA 证书创建设备证书。然后，从要提供给 IoT 中心的证书中检索十六进制“指纹”。 IoT 设备还需要其设备证书的副本，以便可以在 IoT 中心进行身份验证。

Windows
Linux

导航到包含证书生成脚本和根 CA 证书的工作目录 wrkdir。
为下游设备创建两个证书（主要和辅助）。要使用的简易命名约定是依次使用 IoT 设备的名称以及主要标签或辅助标签创建证书。例如：
```
New-CACertsDevice "<device ID>-primary"
New-CACertsDevice "<device ID>-secondary"
```
此脚本命令将创建多个证书和密钥文件。以下证书和密钥对需要复制到下游 IoT 设备，并在连接到 IoT 中心的应用程序中引用：
- certs\iot-device-<device ID>-primary-full-chain.cert.pem
- certs\iot-device-<device ID>-secondary-full-chain.cert.pem
- certs\iot-device-<device ID>-primary.cert.pem
- certs\iot-device-<device ID>-secondary.cert.pem
- certs\iot-device-<device ID>-primary.cert.pfx
- certs\iot-device-<device ID>-secondary.cert.pfx
- private\iot-device-<device ID>-primary.key.pem
- private\iot-device-<device ID>-secondary.key.pem
从每个证书中检索 SHA1 指纹（在 IoT 中心上下文中称为“指纹”）。指纹是由 40 个十六进制字符组成的字符串。使用以下 openssl 命令查看证书并查找指纹：
```
Write-Host (Get-Pfxcertificate -FilePath certs\iot-device-<device name>-primary.cert.pem).Thumbprint
```
运行此命令两次，一次针对主要证书，另一次针对辅助证书。使用自签名的 X.509 证书注册新 IoT 设备时，为这两个证书提供指纹。

导航到包含证书生成脚本和根 CA 证书的工作目录。
为下游设备创建两个证书（主要和辅助）。要使用的简易命名约定是依次使用 IoT 设备的名称以及主要标签或辅助标签创建证书。例如：
```
./certGen.sh create_device_certificate "<device name>-primary"
./certGen.sh create_device_certificate "<device name>-secondary"
```
此脚本命令将创建多个证书和密钥文件。以下证书和密钥对需要复制到下游 IoT 设备，并在连接到 IoT 中心的应用程序中引用：
- certs/iot-device-<device name>-primary-full-chain.cert.pem
- certs/iot-device-<device name>-secondary-full-chain.cert.pem
- certs/iot-device-<device name>-primary.cert.pem
- certs/iot-device-<device name>-secondary.cert.pem
- certs/iot-device-<device name>-primary.cert.pfx
- certs/iot-device-<device name>-secondary.cert.pfx
- private/iot-device-<device name>-primary.key.pem
- private/iot-device-<device name>-secondary.key.pem
从每个证书中检索 SHA1 指纹（在 IoT 中心上下文中称为“指纹”）。指纹是由 40 个十六进制字符组成的字符串。使用以下 openssl 命令查看证书并查找指纹：
```
openssl x509 -in certs/iot-device-<device name>-primary.cert.pem -text -thumbprint | sed 's/[:]//g'
```
使用自签名的 X.509 证书注册新 IoT 设备时，请提供主要指纹和辅助指纹。

CA 签名的证书

使用 CA 签名的证书对 IoT 设备进行身份验证时，需将解决方案的根 CA 证书上传到 IoT 中心。使用同一个根 CA 证书创建要放在 IoT 设备上的设备证书，使设备能够通过 IoT 中心进行身份验证。

本部分中的证书适用于 IoT 中心 X.509 证书教程系列中的步骤。有关此系列的介绍，请参阅了解公钥加密和 X.509 公钥基础结构。

Windows
Linux

将根 CA 证书文件从工作目录 certs\azure-iot-test-only.root.ca.cert.pem 上传到 IoT 中心。
如果未选择自动验证，请使用 Azure 门户中提供的代码验证你是否拥有该根 CA 证书。
```
New-CACertsVerificationCert "<verification code>"
```
创建下游设备的证书链。使用 IoT 中心内用于注册设备的设备 ID。
```
New-CACertsDevice "<device id>"
```
此脚本命令将创建多个证书和密钥文件。以下证书和密钥对需要复制到下游 IoT 设备，并在连接到 IoT 中心的应用程序中引用：
- certs\iot-device-<device id>.cert.pem
- certs\iot-device-<device id>.cert.pfx
- certs\iot-device-<device id>-full-chain.cert.pem
- private\iot-device-<device id>.key.pem

将根 CA 证书文件从工作目录 certs\azure-iot-test-only.root.ca.cert.pem 上传到 IoT 中心。
如果未选择自动验证，请使用 Azure 门户中提供的代码验证你是否拥有该根 CA 证书。
```
./certGen.sh create_verification_certificate "<verification code>"
```
创建下游设备的证书链。使用 IoT 中心内用于注册设备的设备 ID。
```
./certGen.sh create_device_certificate "<device id>"
```
此脚本命令将创建多个证书和密钥文件。以下证书和密钥对需要复制到下游 IoT 设备，并在连接到 IoT 中心的应用程序中引用：
- certs/iot-device-<device id>.cert.pem
- certs/iot-device-<device id>.cert.pfx
- certs/iot-device-<device id>-full-chain.cert.pem
- private/iot-device-<device id>.key.pem

通过