Create demo certificates to test IoT Edge device features

2025-06-06

Applies to: IoT Edge 1.5

Important

IoT Edge 1.5 LTS is the supported release. IoT Edge 1.4 LTS is end of life as of November 12, 2024. If you are on an earlier release, see Update IoT Edge.

IoT Edge devices need certificates for secure communication between the runtime, the modules, and any downstream devices. If you don't have a certificate authority to create the required certificates, use demo certificates to try out IoT Edge features in your test environment. This article explains the certificate generation scripts that IoT Edge provides for testing.

Warning

These certificates expire in 30 days, and you shouldn't use them in any production scenario.

Create certificates on any machine and then copy them to your IoT Edge device, or generate the certificates directly on the IoT Edge device.

Prerequisites

Use a development machine that has Git installed.

Download test certificate scripts and set up working directory

The IoT Edge repository on GitHub includes certificate generation scripts that you can use to create demo certificates. This section provides instructions for preparing the scripts to run on your computer, either on Windows or Linux.

Windows
Linux

To create demo certificates on a Windows device, install OpenSSL, then clone the generation scripts and set them up to run locally in PowerShell.

Install OpenSSL

Install OpenSSL for Windows on the device you use to generate the certificates. If OpenSSL is already installed, make sure that openssl.exe is available in your PATH environment variable.

You can install OpenSSL in different ways:

Easier: Download and install any third-party OpenSSL binaries, for example, from OpenSSL on SourceForge. Add the full path to openssl.exe to your PATH environment variable.
Recommended: Download the OpenSSL source code and build the binaries on your device, or use vcpkg. The following instructions use vcpkg to download source code, compile, and install OpenSSL on your Windows device.
1. Navigate to a directory where you want to install vcpkg. Follow the instructions to download and install vcpkg.
2. Once vcpkg is installed, run the following command from a PowerShell prompt to install the OpenSSL package for Windows x64. The installation typically takes about 5 minutes to complete.
```
.\vcpkg install openssl:x64-windows
```
3. Add <vcpkg path>\installed\x64-windows\tools\openssl to your PATH environment variable so that the openssl.exe file is available for invocation.

Prepare scripts in PowerShell

The Azure IoT Edge git repository contains scripts that you can use to generate test certificates. In this section, you clone the IoT Edge repository and execute the scripts.

Open PowerShell in administrator mode.
Clone the IoT Edge git repository, which has scripts to generate demo certificates. Use the git clone command or download the ZIP.
```
git clone https://github.com/Azure/iotedge.git
```
Create a directory and copy the certificate scripts there. All certificate and key files are created in this directory.
```
mkdir wrkdir
cd .\wrkdir\
cp ..\iotedge\tools\CACertificates\*.cnf .
cp ..\iotedge\tools\CACertificates\ca-certs.ps1 .
```
If you downloaded the repository as a ZIP, the folder name is iotedge-master and the rest of the path is the same.

Set the PowerShell execution policy to run the scripts.

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

Import the functions used by the scripts into PowerShell's global namespace.
```
. .\ca-certs.ps1
```
The PowerShell window shows a warning that the certificates generated by this script are only for testing, and shouldn't be used in production scenarios.
Verify that OpenSSL has been installed correctly and make sure that there won't be name collisions with existing certificates. If there are problems, the script output should describe how to fix them on your system.
```
Test-CACertsPrerequisites
```

To create demo certificates on a Linux device, you need to clone the generation scripts and set them up to run locally in bash.

Clone the IoT Edge git repository, which contains scripts to generate demo certificates.
```
git clone https://github.com/Azure/iotedge.git
```
Create a directory and copy the certificate scripts there. All certificate and key files are created in this directory.
```
mkdir wrkdir
cd wrkdir
cp ../iotedge/tools/CACertificates/*.cnf .
cp ../iotedge/tools/CACertificates/certGen.sh .
```

Create root CA certificate

Run this script to generate a root CA certificate. You need this certificate for each step in this article.

Use the root CA certificate to create other demo certificates for testing an IoT Edge scenario. You can use the same root CA certificate to create demo certificates for multiple IoT Edge or downstream devices.

If you already have a root CA certificate in your working folder, don't create a new one. Creating a new root CA certificate overwrites the old one, and any downstream certificates created from the old certificate stop working. If you need multiple root CA certificates, manage them in separate folders.

Windows
Linux

Go to the working directory wrkdir where you put the certificate generation scripts.
Create the root CA certificate and sign one intermediate certificate. The certificates are placed in your working directory.
```
New-CACertsCertChain rsa
```
This script creates several certificate and key files. When articles ask for the root CA certificate, use this file:

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

Go to the working directory wrkdir where you put the certificate generation scripts.
Create the root CA certificate and one intermediate certificate.
```
./certGen.sh create_root_and_intermediate
```
This script creates several certificate and key files. When articles ask for the root CA certificate, use this file:

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

You need this certificate before you create more certificates for your IoT Edge devices and downstream devices, as described in the next sections.

Create identity certificate for the IoT Edge device

IoT Edge device identity certificates are used to provision IoT Edge devices if you choose to use X.509 certificate authentication. If you use symmetric key for authenticating to IoT Hub or DPS, these certificates aren't needed, and you can skip this section.

These certificates work whether you use manual provisioning or automatic provisioning through the Azure IoT Hub Device Provisioning Service (DPS).

Device identity certificates go in the Provisioning section of the config file on the IoT Edge device.

Windows
Linux

Go to the working directory wrkdir that has the certificate generation scripts and root CA certificate.
Create the IoT Edge device identity certificate and private key with the following command:
```
New-CACertsEdgeDeviceIdentity "<device-id>"
```
The name you enter for this command is the device ID for the IoT Edge device in IoT Hub.

The new device identity command creates several certificate and key files:

Type	File	Description
Device identity certificate	`certs\iot-edge-device-identity-<device-id>.cert.pem`	Signed by the intermediate certificate generated earlier. Contains just the identity certificate. Specify in configuration file for DPS individual enrollment or IoT Hub provisioning.
Full chain certificate	`certs\iot-edge-device-identity-<device-id>-full-chain.cert.pem`	Contains the full certificate chain including the intermediate certificate. Specify in configuration file for IoT Edge to present to DPS for group enrollment provisioning.
Private key	`private\iot-edge-device-identity-<device-id>.key.pem`	Private key associated with the device identity certificate. Should be specified in configuration file as long as you're using some sort of certificate authentication (thumbprint or CA) for either DPS or IoT Hub.

Navigate to the working directory wrkdir that has the certificate generation scripts and root CA certificate.
Create the IoT Edge device identity certificate and private key with the following command:
```
./certGen.sh create_edge_device_identity_certificate "<device-id>"
```
The name that you pass in to this command is the device ID for the IoT Edge device in IoT Hub.

The script creates several certificate and key files, including three that you use when creating an individual enrollment in DPS and installing the IoT Edge runtime:

Type	File	Description
Device identity certificate	`certs/iot-edge-device-identity-<device-id>.cert.pem`	Signed by the intermediate certificate generated earlier. Contains just the identity certificate. Specify in configuration file for DPS individual enrollment or IoT Hub provisioning.
Full chain certificate	`certs/iot-edge-device-identity-<device-id>-full-chain.cert.pem`	Contains the full certificate chain including the intermediate certificate. Specify in configuration file for IoT Edge to present to DPS for group enrollment provisioning.
Private key	`private/iot-edge-device-identity-<device-id>.key.pem`	Private key associated with the device identity certificate. Should be specified in configuration file as long as you're using some sort of certificate authentication (thumbprint or CA) for either DPS or IoT Hub.

Create Edge CA certificates

You need these certificates for gateway scenarios because the Edge CA certificate lets the IoT Edge device verify its identity to downstream devices. Skip this section if you aren't connecting any downstream devices to IoT Edge.

The Edge CA certificate also creates certificates for modules running on the device, but the IoT Edge runtime can create temporary certificates if Edge CA isn't set up. Place Edge CA certificates in the Edge CA section of the config.toml file on the IoT Edge device. To learn more, see Understand how Azure IoT Edge uses certificates.

Windows
Linux

Navigate to the working directory wrkdir that has the certificate generation scripts and root CA certificate.
Create the IoT Edge CA certificate and private key with the following command. Enter a name for the CA certificate. Don't use the same name as the hostname parameter in the config file or the device's ID in IoT Hub for the New-CACertsEdgeDevice command.
```
New-CACertsEdgeDevice "<CA cert name>"
```
This command creates several certificate and key files. Copy the following certificate and key pair to the IoT Edge device and reference them in the config file:
- certs\iot-edge-device-<CA cert name>-full-chain.cert.pem
- private\iot-edge-device-<CA cert name>.key.pem

Navigate to the working directory that has the certificate generation scripts and root CA certificate.
Create the IoT Edge CA certificate and private key with the following command. Enter a name for the CA certificate. Don't use the same name as the hostname parameter in the config file or the device's ID in IoT Hub for the create_edge_device_ca_certificate command.
```
./certGen.sh create_edge_device_ca_certificate "<CA cert name>"
```
This script command creates several certificate and key files. Copy the following certificate and key pair to the IoT Edge device and reference them in the config file:
- certs/iot-edge-device-ca-<CA cert name>-full-chain.cert.pem
- private/iot-edge-device-ca-<CA cert name>.key.pem

Create downstream device certificates

These certificates are required for setting up a downstream IoT device for a gateway scenario and want to use X.509 authentication with IoT Hub or DPS. If you want to use symmetric key authentication, you don't need to create certificates for the downstream device and can skip this section.

There are two ways to authenticate an IoT device using X.509 certificates: using self-signed certs or using certificate authority (CA) signed certs.

For X.509 self-signed authentication, sometimes referred to as thumbprint authentication, you need to create new certificates to place on your IoT device. These certificates have a thumbprint in them that you share with IoT Hub for authentication.
For X.509 certificate authority (CA) signed authentication, you need a root CA certificate registered in IoT Hub or DPS that you use to sign certificates for your IoT device. Any device using a certificate that was issued by the root CA certificate or any of its intermediate certificates can authenticate as long as the full chain is presented by the device.

The certificate generation scripts can help you make demo certificates to test out either of these authentication scenarios.

Self-signed certificates

When you authenticate an IoT device with self-signed certificates, you need to create device certificates based on the root CA certificate for your solution. Then, you retrieve a hexadecimal "thumbprint" from the certificates to provide to IoT Hub. Your IoT device also needs a copy of its device certificates so that it can authenticate with IoT Hub.

Windows
Linux

Navigate to the working directory wrkdir that has the certificate generation scripts and root CA certificate.
Create two certificates (primary and secondary) for the downstream device. An easy naming convention to use is to create the certificates with the name of the IoT device and then the primary or secondary label. For example:
```
New-CACertsDevice "<device ID>-primary"
New-CACertsDevice "<device ID>-secondary"
```
This script command creates several certificate and key files. The following certificate and key pairs needs to be copied over to the downstream IoT device and referenced in the applications that connect to IoT Hub:
- 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
Retrieve the SHA1 thumbprint (called a thumbprint in IoT Hub contexts) from each certificate. The thumbprint is a 40 hexadecimal character string. Use the following openssl command to view the certificate and find the thumbprint:
```
Write-Host (Get-Pfxcertificate -FilePath certs\iot-device-<device name>-primary.cert.pem).Thumbprint
```
Run this command twice, once for the primary certificate and once for the secondary certificate. You provide thumbprints for both certificates when you register a new IoT device using self-signed X.509 certificates.

Navigate to the working directory that has the certificate generation scripts and root CA certificate.
Create two certificates (primary and secondary) for the downstream device. An easy naming convention to use is to create the certificates with the name of the IoT device and then the primary or secondary label. For example:
```
./certGen.sh create_device_certificate "<device name>-primary"
./certGen.sh create_device_certificate "<device name>-secondary"
```
This script command creates several certificate and key files. The following certificate and key pairs needs to be copied over to the downstream IoT device and referenced in the applications that connect to IoT Hub:
- 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
Retrieve the SHA1 thumbprint (called a thumbprint in IoT Hub contexts) from each certificate. The thumbprint is a 40 hexadecimal character string. Use the following openssl command to view the certificate and find the thumbprint:
```
openssl x509 -in certs/iot-device-<device name>-primary.cert.pem -text -thumbprint | sed 's/[:]//g'
```
You provide both the primary and secondary thumbprint when you register a new IoT device using self-signed X.509 certificates.

CA-signed certificates

When you authenticate an IoT device with CA-signed certificates, you need to upload the root CA certificate for your solution to IoT Hub. Use the same root CA certificate to create device certificates to put on your IoT device so that it can authenticate with IoT Hub.

The certificates in this section are for the steps in the IoT Hub X.509 certificate tutorial series. See Understanding Public Key Cryptography and X.509 Public Key Infrastructure for the introduction of this series.

Windows
Linux

Upload the root CA certificate file from your working directory, certs\azure-iot-test-only.root.ca.cert.pem, to your IoT hub.
If automatic verification isn't selected, use the code provided in the Azure portal to verify that you own that root CA certificate.
```
New-CACertsVerificationCert "<verification code>"
```
Create a certificate chain for your downstream device. Use the same device ID that the device is registered with in IoT Hub.
```
New-CACertsDevice "<device id>"
```
This script command creates several certificate and key files. The following certificate and key pairs needs to be copied over to the downstream IoT device and referenced in the applications that connect to IoT Hub:
- 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

Upload the root CA certificate file from your working directory, certs\azure-iot-test-only.root.ca.cert.pem, to your IoT hub.
If automatic verification isn't selected, use the code provided in the Azure portal to verify that you own that root CA certificate.
```
./certGen.sh create_verification_certificate "<verification code>"
```
Create a certificate chain for your downstream device. Use the same device ID that the device is registered with in IoT Hub.
```
./certGen.sh create_device_certificate "<device id>"
```
This script command creates several certificate and key files. The following certificate and key pairs needs to be copied over to the downstream IoT device and referenced in the applications that connect to IoT Hub:
- 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

Share via