管理 IoT Edge 设备上的证书Manage certificates on an IoT Edge device

所有 IoT Edge 设备使用证书在运行时与设备上运行的任何模块之间创建安全连接。All IoT Edge devices use certificates to create secure connections between the runtime and any modules running on the device. 充当网关的 IoT Edge 设备也使用相同的证书连接到其下游设备。IoT Edge devices functioning as gateways use these same certificates to connect to their downstream devices, too.

安装生产证书Install production certificates

首次安装 IoT Edge 和预配设备时,将在设备上设置临时证书,使你能够测试服务。When you first install IoT Edge and provision your device, the device is set up with temporary certificates so that you can test the service. 这些临时证书将在 90 天后过期,重启计算机可以重置这些证书。These temporary certificates expire in 90 days, or can be reset by restarting your machine. 一旦转移到生产方案,或者想要创建网关设备,就需要提供自己的证书。Once you move into a production scenario, or you want to create a gateway device, you need to provide your own certificates. 本文演示在 IoT Edge 设备上安装证书的步骤。This article demonstrates the steps to install certificates on your IoT Edge devices.

若要详细了解不同类型的证书及其角色,请参阅了解 Azure IoT Edge 如何使用证书To learn more about the different types of certificates and their roles, see Understand how Azure IoT Edge uses certificates.

备注

整篇文章中使用的术语“根 CA”是指 IoT 解决方案证书链的最顶层颁发机构公共证书。The term "root CA" used throughout this article refers to the topmost authority public certificate of the certificate chain for your IoT solution. 不需要使用联合证书颁发机构的证书根,也不需要使用组织证书颁发机构的根。You do not need to use the certificate root of a syndicated certificate authority, or the root of your organization's certificate authority. 在许多情况下,它实际上是中间 CA 公共证书。In many cases, it is actually an intermediate CA public certificate.

先决条件Prerequisites

  • WindowsLinux 上运行的 IoT Edge 设备。An IoT Edge device, running either on Windows or Linux.
  • 有一个根证书颁发机构 (CA) 证书,该证书是自签名证书,或者从 Baltimore、Verisign、DigiCert 或 GlobalSign 等可信商业证书颁发机构购买的证书。Have a root certificate authority (CA) certificate, either self-signed or purchased from a trusted commercial certificate authority like Baltimore, Verisign, DigiCert, or GlobalSign.

如果你没有根证书颁发机构,但想要试用需要生产证书的 IoT Edge 功能(例如网关方案),可以创建演示证书来测试 IoT Edge 设备功能If you don't have a root certificate authority yet, but want to try out IoT Edge features that require production certificates (like gateway scenarios) you can Create demo certificates to test IoT Edge device features.

创建生产证书Create production certificates

应使用自己的证书颁发机构创建以下文件:You should use your own certificate authority to create the following files:

  • 根 CARoot CA
  • 设备 CA 证书Device CA certificate
  • 设备 CA 私钥Device CA private key

本文中所谓的“根 CA”并非组织的最顶层证书颁发机构。In this article, what we refer to as the root CA is not the topmost certificate authority for an organization. 它是 IoT Edge 方案的最顶层证书颁发机构,IoT Edge 中心模块、用户模块和任何下游设备使用该颁发机构来建立彼此之间的信任。It's the topmost certificate authority for the IoT Edge scenario, which the IoT Edge hub module, user modules, and any downstream devices use to establish trust between each other.

备注

目前存在一个 libiothsm 限制,会阻止使用在 2050 年 1 月 1 日或之后过期的证书。Currently, a limitation in libiothsm prevents the use of certificates that expire on or after January 1, 2050.

若要查看这些证书的示例,请查看管理用于示例和教程的测试 CA 证书中用于创建演示证书的脚本。To see an example of these certificates, review the scripts that create demo certificates in Managing test CA certificates for samples and tutorials.

在设备上安装证书Install certificates on the device

在 IoT Edge 设备上安装证书链,并将 IoT Edge 运行时配置为引用新证书。Install your certificate chain on the IoT Edge device and configure the IoT Edge runtime to reference the new certificates.

例如,如果使用示例脚本创建了演示证书,请将以下文件复制到 IoT-Edge 设备:For example, if you used the sample scripts to Create demo certificates, copy the following files onto your IoT-Edge device:

  • 设备 CA 证书:<WRKDIR>\certs\iot-edge-device-MyEdgeDeviceCA-full-chain.cert.pemDevice CA certificate: <WRKDIR>\certs\iot-edge-device-MyEdgeDeviceCA-full-chain.cert.pem
  • 设备 CA 私钥:<WRKDIR>\private\iot-edge-device-MyEdgeDeviceCA.key.pemDevice CA private key: <WRKDIR>\private\iot-edge-device-MyEdgeDeviceCA.key.pem
  • 根 CA:<WRKDIR>\certs\azure-iot-test-only.root.ca.cert.pemRoot CA: <WRKDIR>\certs\azure-iot-test-only.root.ca.cert.pem
  1. 将三个证书和密钥文件复制到 IoT Edge 设备。Copy the three certificate and key files onto your IoT Edge device.

    可以使用 Azure Key Vault 之类的服务或安全复制协议之类的功能来移动证书文件。You can use a service like Azure Key Vault or a function like Secure copy protocol to move the certificate files. 如果在 IoT Edge 设备本身上生成了证书,则可以跳过此步骤,并使用工作目录的路径。If you generated the certificates on the IoT Edge device itself, you can skip this step and use the path to the working directory.

  2. 打开 IoT Edge 安全守护程序配置文件。Open the IoT Edge security daemon config file.

    • Windows: C:\ProgramData\iotedge\config.yamlWindows: C:\ProgramData\iotedge\config.yaml
    • Linux:/etc/iotedge/config.yamlLinux: /etc/iotedge/config.yaml
  3. 将 config.yaml 文件中的 certificate 属性设置为 IoT Edge 设备上的证书和密钥文件的文件 URI 路径。Set the certificate properties in config.yaml to the file URI path to the certificate and key files on the IoT Edge device. 删除 certificate 属性前面的 # 字符,以取消注释四个代码行。Remove the # character before the certificate properties to uncomment the four lines. 请确保 certificates: 行前面没有空格,并且嵌套项缩进了两个空格。Make sure the certificates: line has no preceding whitespace and that nested items are indented by two spaces. 例如:For example:

    • Windows:Windows:

      certificates:
         device_ca_cert: "file:///C:/<path>/<device CA cert>"
         device_ca_pk: "file:///C:/<path>/<device CA key>"
         trusted_ca_certs: "file:///C:/<path>/<root CA cert>"
      
    • Linux:Linux:

      certificates:
         device_ca_cert: "file:///<path>/<device CA cert>"
         device_ca_pk: "file:///<path>/<device CA key>"
         trusted_ca_certs: "file:///<path>/<root CA cert>"
      
  4. 在 Linux 设备上,确保用户 iotedge 对保存证书的目录拥有读取权限。On Linux devices, make sure that the user iotedge has read permissions for the directory holding the certificates.

  5. 如果以前在设备上使用过 IoT Edge 的任何其他证书,请在启动或重启 IoT Edge 之前删除以下两个目录中的文件:If you've used any other certificates for IoT Edge on the device before, delete the files in the following two directories before starting or restarting IoT Edge:

    • Windows:C:\ProgramData\iotedge\hsm\certsC:\ProgramData\iotedge\hsm\cert_keysWindows: C:\ProgramData\iotedge\hsm\certs and C:\ProgramData\iotedge\hsm\cert_keys

    • Linux:/var/lib/iotedge/hsm/certs/var/lib/iotedge/hsm/cert_keysLinux: /var/lib/iotedge/hsm/certs and /var/lib/iotedge/hsm/cert_keys

自定义证书生存期Customize certificate lifetime

在多种情况下,IoT Edge 会在设备上自动生成证书,这些情况包括:IoT Edge automatically generates certificates on the device in several cases, including:

  • 如果你在安装和预配 IoT Edge 时未提供自己的生产证书,则 IoT Edge 安全管理器会自动生成一个设备 CA 证书。If you don't provide your own production certificates when you install and provision IoT Edge, the IoT Edge security manager automatically generates a device CA certificate. 这个自签名证书仅用于开发和测试方案,而不可用于生产。This self-signed certificate is only meant for development and testing scenarios, not production. 此证书在 90 天后过期。This certificate expires after 90 days.
  • IoT Edge 安全管理器还会生成由设备 CA 证书签名的工作负荷 CA 证书The IoT Edge security manager also generates a workload CA certificate signed by the device CA certificate

有关 IoT Edge 设备上不同证书的功能的详细信息,请参阅了解 Azure IoT Edge 如何使用证书For more information about the function of the different certificates on an IoT Edge device, see Understand how Azure IoT Edge uses certificates.

对于这两个自动生成的证书,可以选择在 config.yaml 中设置 auto_generated_ca_lifetime_days 标志,以配置证书生存期的天数。For these two automatically generated certificates, you have the option of setting the auto_generated_ca_lifetime_days flag in config.yaml to configure the number of days for the lifetime of the certificates.

备注

IoT Edge 安全管理器还会创建第三个自动生成的证书:IoT Edge 中心服务器证书。There is a third auto-generated certificate that the IoT Edge security manager creates, the IoT Edge hub server certificate. 此证书的生存期始终为 90 天,但过期之前会自动续订。This certificate always has a 90 day lifetime, but is automatically renewed before expiring. auto_generated_ca_lifetime_days 值不会影响此证书。The auto_generated_ca_lifetime_days value doesn't affect this certificate.

若要将证书过期时间配置为超过默认 90 天,请在 config.yaml 文件的 certificates 节中添加所需值(以天为单位)。To configure the certificate expiration to something other than the default 90 days, add the value in days to the certificates section of the config.yaml file.

certificates:
  device_ca_cert: "<ADD URI TO DEVICE CA CERTIFICATE HERE>"
  device_ca_pk: "<ADD URI TO DEVICE CA PRIVATE KEY HERE>"
  trusted_ca_certs: "<ADD URI TO TRUSTED CA CERTIFICATES HERE>"
  auto_generated_ca_lifetime_days: <value>

备注

目前存在一个 libiothsm 限制,会阻止使用在 2050 年 1 月 1 日或之后过期的证书。Currently, a limitation in libiothsm prevents the use of certificates that expire on or after January 1, 2050.

如果提供了自己的设备 CA 证书,则此值仍会应用到工作负荷 CA 证书,前提是设置的生存期值短于设备 CA 证书的生存期。If you provided your own device CA certificates, then this value still applies to the workload CA certificate, provided the lifetime value you set is shorter than the lifetime of the device CA certificate.

在 config.yaml 文件中指定标志后,请执行以下步骤:After you specify the flag in the config.yaml file, take the following steps:

  1. 删除 hsm 文件夹的内容。Delete the contents of the hsm folder.

    Windows:C:\ProgramData\iotedge\hsm\certs and C:\ProgramData\iotedge\hsm\cert_keys Linux:/var/lib/iotedge/hsm/certs and /var/lib/iotedge/hsm/cert_keysWindows: C:\ProgramData\iotedge\hsm\certs and C:\ProgramData\iotedge\hsm\cert_keys Linux: /var/lib/iotedge/hsm/certs and /var/lib/iotedge/hsm/cert_keys

  2. 重启 IoT Edge 服务。Restart the IoT Edge service.

    Windows:Windows:

    Restart-Service iotedge
    

    Linux:Linux:

    sudo systemctl restart iotedge
    
  3. 确认生存期设置。Confirm the lifetime setting.

    Windows:Windows:

    iotedge check --verbose
    

    Linux:Linux:

    sudo iotedge check --verbose
    

    查看“生产就绪状态: 证书”检查的输出,其中列出了自动生成的设备 CA 证书在过期前的天数。Check the output of the production readiness: certificates check, which lists the number of days until the automatically generated device CA certificates expire.

后续步骤Next steps

在生产环境中部署解决方案之前,必须先在 IoT Edge 设备上安装证书。Installing certificates on an IoT Edge device is a necessary step before deploying your solution in production. 详细了解如何准备在生产环境中部署 IoT Edge 解决方案Learn more about how to Prepare to deploy your IoT Edge solution in production.