Create demo certificates to test IoT Edge device features

Article
05/05/2023

Applies to: IoT Edge 1.4

Important

IoT Edge 1.4 is the supported release. If you are on an earlier release, see Update IoT Edge.

IoT Edge devices require 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, you can use demo certificates to try out IoT Edge features in your test environment. This article describes the functionality of the certificate generation scripts that IoT Edge provides for testing.

Warning

These certificates expire in 30 days, and should not be used in any production scenario.

You can create certificates on any machine and then copy them over to your IoT Edge device, or generate the certificates directly on the IoT Edge device.

Prerequisites

A development machine with 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, you need to install OpenSSL and then clone the generation scripts and set them up to run locally in PowerShell.

Install OpenSSL

Install OpenSSL for Windows on the machine that you're using to generate the certificates. If you already have OpenSSL installed on your Windows device, ensure that openssl.exe is available in your PATH environment variable.

There are several ways to install OpenSSL, including the following options:

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 machine by yourself or via vcpkg. The instructions listed below use vcpkg to download source code, compile, and install OpenSSL on your Windows machine with easy steps.
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 repo and execute the scripts.

Open a PowerShell window in administrator mode.
Clone the IoT Edge git repo, which contains 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 in which you want to work and copy the certificate scripts there. All certificate and key files will be created in this directory.
```
mkdir wrkdir
cd .\wrkdir\
cp ..\iotedge\tools\CACertificates\*.cnf .
cp ..\iotedge\tools\CACertificates\ca-certs.ps1 .
```
If you downloaded the repo as a ZIP, then the folder name is iotedge-master and the rest of the path is the same.

Enable PowerShell to run the scripts.

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

Bring the functions used by the scripts into PowerShell's global namespace.
```
. .\ca-certs.ps1
```
The PowerShell window will display a warning that the certificates generated by this script are only for testing purposes, and should not 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 repo, which contains scripts to generate demo certificates.
```
git clone https://github.com/Azure/iotedge.git
```
Create a directory in which you want to work and copy the certificate scripts there. All certificate and key files will be 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 that is required for each step in this article.

The root CA certificate is used to make all the other demo certificates for testing an IoT Edge scenario. You can keep using the same root CA certificate to make demo certificates for multiple IoT Edge or downstream devices.

If you already have one root CA certificate in your working folder, don't create a new one. The new root CA certificate will overwrite the old, and any downstream certificates made from the old one will stop working. If you want multiple root CA certificates, be sure to manage them in separate folders.

Windows
Linux

Navigate to the working directory wrkdir where you placed the certificate generation scripts.
Create the root CA certificate and have it sign one intermediate certificate. The certificates are all placed in your working directory.
```
New-CACertsCertChain rsa
```
This script command creates several certificate and key files, but when articles ask for the root CA certificate, use the following file:

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

Navigate to the working directory wrkdir where you placed the certificate generation scripts.
Create the root CA certificate and one intermediate certificate.
```
./certGen.sh create_root_and_intermediate
```
This script command creates several certificate and key files, but when articles ask for the root CA certificate, use the following file:

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

This certificate is required before you can 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

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:
```
New-CACertsEdgeDeviceIdentity "<device-id>"
```
The name that you pass in to 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

These certificates are required for gateway scenarios because the edge CA certificate is how the IoT Edge device verifies its identity to downstream devices. You can skip this section if you're not connecting any downstream devices to IoT Edge.

The edge CA certificate is also responsible for creating certificates for modules running on the device, but IoT Edge runtime can create temporary certificates if edge CA isn't configured. Edge CA certificates go 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. Provide a name for the CA certificate. The name passed to the New-CACertsEdgeDevice command should not be the same as the hostname parameter in the config file or the device's ID in IoT Hub.
```
New-CACertsEdgeDevice "<CA cert name>"
```
This command creates several certificate and key files. The following certificate and key pair need to be copied over to an IoT Edge device and referenced 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

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. Provide a name for the CA certificate. The name passed to the create_edge_device_ca_certificate command should not be the same as the hostname parameter in the config file or the device's ID in IoT Hub.
```
./certGen.sh create_edge_device_ca_certificate "<CA cert name>"
```
This script command creates several certificate and key files. The following certificate and key pair need to be copied over to an IoT Edge device and referenced 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