Manage IoT Edge certificates

Applies to: IoT Edge 1.1

Important

IoT Edge 1.1 end of support date was December 13, 2022. Check the Microsoft Product Lifecycle for information about how this product, service, technology, or API is supported. For more information about updating to the latest version of IoT Edge, see Update IoT Edge.

All IoT Edge devices use certificates to create secure connections between the runtime and any modules running on the device. IoT Edge devices functioning as gateways use these same certificates to connect to their downstream devices, too. For more information about the function of the different certificates on an IoT Edge device, see Understand how Azure IoT Edge uses certificates.

Note

The term root CA used throughout this article refers to the topmost authority's certificate in 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. In many cases, it is actually an intermediate CA certificate.

Prerequisites

• Understand how Azure IoT Edge uses certificates.

• An IoT Edge device. If you don't have an IoT Edge device set up, you can create one in an Azure virtual machine. Follow the steps in one of the quickstart articles to Create a virtual Linux device or Create a virtual Windows device.

• Ability to edit the IoT Edge configuration file config.toml following the configuration template.

  • If your config.toml isn't based on the template, open the template and use the commented guidance to add configuration sections following the structure of the template.

  • If you have a new IoT Edge installation that hasn't been configured, copy the template to initialize the configuration. Don't use this command if you have an existing configuration. It overwrites the file.

    sudo cp /etc/aziot/config.toml.edge.template /etc/aziot/config.toml
    

Device CA

All IoT Edge devices use certificates to create secure connections between the runtime and any modules running on the device. IoT Edge devices functioning as gateways use these same certificates to connect to their downstream devices, too. For more information about the function of the different certificates on an IoT Edge device, see Understand how Azure IoT Edge uses certificates.

IoT Edge automatically generates device CA on the device in several cases, including:

• 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. This certificate expires after 90 days.
• The IoT Edge security manager also generates a workload CA certificate signed by the device CA certificate.

For these two automatically generated certificates, you have the option of setting a flag in the config file to configure the number of days for the lifetime of the certificates.

Note

There is a third auto-generated certificate that the IoT Edge security manager creates, the IoT Edge hub server certificate. This certificate always has a 30 day lifetime, but is automatically renewed before expiring. The auto-generated CA lifetime value set in the config file doesn't affect this certificate.

Customize quickstart device CA certificate lifetime

Upon expiry after the specified number of days, IoT Edge has to be restarted to regenerate the device CA certificate. The device CA certificate isn't renewed automatically.

Linux containers

1. 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 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>
   

   Note

   Currently, a limitation in libiothsm prevents the use of certificates that expire on or after January 1, 2038.

2. Delete the contents of the hsm folder to remove any previously generated certificates.

   • /var/aziot/hsm/certs
   • /var/aziot/hsm/cert_keys

3. Restart the IoT Edge service.

   sudo systemctl restart iotedge
   

4. Confirm the lifetime setting.

   sudo iotedge check --verbose
   

   Check the output of the production readiness: certificates check, which lists the number of days until the automatically generated device CA certificates expire.

Windows containers

1. 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 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>
   

   Note

   Currently, a limitation in libiothsm prevents the use of certificates that expire on or after January 1, 2038.

2. Delete the contents of the hsm folder to remove any previously generated certificates.

   • C:\ProgramData\iotedge\hsm\certs
   • C:\ProgramData\iotedge\hsm\cert_keys

3. Restart the IoT Edge service.

   Restart-Service iotedge
   

4. Confirm the lifetime setting.

   iotedge check --verbose
   

   Check the output of the production readiness: certificates check, which lists the number of days until the automatically generated device CA certificates expire.

Install device CA for production

Once you move into a production scenario, or you want to create a gateway device, you need to provide your own certificates.

Create and install device CA for production

1. Use your own certificate authority to create the following files:

   • Root CA
   • Device CA certificate
   • Device CA private key

   The root CA isn't the topmost certificate authority for an organization. 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.

   To see an example of these certificates, review the scripts that create demo certificates in Managing test CA certificates for samples and tutorials.

   Note

   Currently, a limitation in libiothsm prevents the use of certificates that expire on or after January 1, 2038.

2. Copy the three certificate and key files onto your IoT Edge device. You can use a service like Azure Key Vault or a function like Secure copy protocol to move the certificate files. If you generated the certificates on the IoT Edge device itself, you can skip this step and use the path to the working directory.

   Tip

   If you used the sample scripts to create demo certificates, the three certificate and key files are located at the following paths:

   • Device CA certificate: <WRKDIR>\certs\iot-edge-device-MyEdgeDeviceCA-full-chain.cert.pem
   • Device CA private key: <WRKDIR>\private\iot-edge-device-MyEdgeDeviceCA.key.pem
   • Root CA: <WRKDIR>\certs\azure-iot-test-only.root.ca.cert.pem

Linux containers

1. Open the IoT Edge security daemon config file: /etc/iotedge/config.yaml

2. Set the certificate properties in config.yaml to the file URI path to the certificate and key files on the IoT Edge device. Remove the # character before the certificate properties to uncomment the four lines. Make sure the certificates: line has no preceding whitespace and that nested items are indented by two spaces. For example:

   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>"
   

3. Make sure that the user iotedge has read/write permissions for the directory holding the certificates.

4. 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:

   • /var/aziot/hsm/certs
   • /var/aziot/hsm/cert_keys

5. Restart IoT Edge.

   sudo iotedge system restart
   

Windows containers

1. Open the IoT Edge security daemon config file: C:\ProgramData\iotedge\config.yaml

2. Set the certificate properties in config.yaml to the file URI path to the certificate and key files on the IoT Edge device. Remove the # character before the certificate properties to uncomment the four lines. Make sure the certificates: line has no preceding whitespace and that nested items are indented by two spaces. For example:

   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>"
   

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

   • C:\ProgramData\iotedge\hsm\certs
   • C:\ProgramData\iotedge\hsm\cert_keys

4. Restart IoT Edge.

   Restart-Service iotedge
   

Module server certificates

Edge Daemon issues module server and identity certificates for use by Edge modules. It remains the responsibility of Edge modules to renew their identity and server certificates as needed.

Renewal

Server certificates may be issued off the Edge CA certificate or through a DPS-configured CA. Regardless of the issuance method, these certificates must be renewed by the module.

Changes in 1.2 and later

• The Device CA certificate was renamed as Edge CA certificate.
• The workload CA certificate was deprecated. Now the IoT Edge security manager generates the IoT Edge hub edgeHub server certificate directly from the Edge CA certificate, without the intermediate workload CA certificate between them.
• The default config file has a new name and location, from /etc/iotedge/config.yaml to /etc/aziot/config.toml by default. The iotedge config import command can be used to help migrate configuration information from the old location and syntax to the new one.

Next steps

Installing certificates on an IoT Edge device is a necessary step before deploying your solution in production. Learn more about how to Prepare to deploy your IoT Edge solution in production.