How To Create IoT Edge Gateway Certificate

Prerequisites

  1. An Azure IoT Hub Instance
  2. A Linux Machine running IoT Edge.

Overview

All IoT Edge gateways need a device CA certificate installed on them. The IoT Edge security daemon uses the IoT Edge device CA certificate to sign a workload CA certificate, which in turn signs a server certificate for IoT Edge hub. The gateway presents its server certificate to the downstream device during the initiation of the connection. The downstream device checks to make sure that the server certificate is part of a certificate chain that rolls up to the root CA certificate. This process allows the downstream device to confirm that the gateway comes from a trusted source. In this page we will walk though the steps required to Set up the device CA Certificate

Creating Certificate Authorities

IoT edge requires a device certificate that is signed by a root CA and a Intermediate CA. We will start by creating these two CAs in EZCA. Azure IoT Hub Gateway device certificates

Creating a Root CA in Azure

  1. Go to https://portal.ezca.io/
  2. Login with an account that is registered as a PKI Admin in EZCA.
  3. Navigate to Certificate Authorities. Azure Certificate Authority Menu
  4. Click on the “Create CA” Create CA in Azure
  5. Select Root CA. Select CA Root Type
  6. Click Next

Entering CA Information

  1. Enter Common Name: This is the name of the CA how it will appear in the certificate.
  2. (Optional) Enter CA Friendly Name This is the name that will appear in the EZCA portal, by default we will use the Common Name
  3. (Optional) Enter the Organization The Organization field is an optional certificate field that usually has the company name.
  4. (Optional) Enter the Organization Unit The Organization Unit field is an optional certificate field that usually contains the unit that runs this CA (For example: IT or HR).
  5. (Optional) Enter the Country Code The Country Code field is an optional certificate field that identifies the country where this CA is located.
  6. Click Next. CA Details

Cryptographic Requirements

  1. Unless you have specific compliance or security requirements, leave the default cryptographic values for best security and compatibility. Set Certificate Authority Cryptographic Details

Validity Period

  1. Select your Validity Period Learn more about Validity Period best practices, keep in mind how you will update this certificate in your IoT devices and the lifetime of your IoT devices.
  2. Enter a Notification Email this email address (as well as the PKI Administrators) will get all the notifications for the lifecycle of the CA.
  3. Select the lifecycle action you want EZCA to take when expiry of the CA is approaching

    For Root CAs we recommend to have a manual Lifecycle since the new Root will have to be added to the trusted root stores of your clients which requires manual steps from the IT team.

  4. Select the percentage of lifetime of the certificate when you want EZCA to start taking Lifecycle actions. Certificate Authority Lifecycle Details

CA Certificate Revocation List

  1. Select if you want this CA should issue a CRL (Highly recommended)
  2. Click Next. Azure CA CRL (revocation) Details

CA Certificate Revocation List Advance Settings

Changes to this section are only recommended for PKI experts with specific requirements.

  1. Click the expand button Azure CA CRL Setup Details
  2. Enter the desired CRL Validity Period in days
  3. Enter the desired CRL Overlap Period in hours
  4. (Optional) Enter the CRL endpoint where you will publish your CRLs

    Custom CRL endpoints are supported by EZCA by adding the CRL endpoint as the CRL endpoint in the certificate. However, your PKI admins are responsible from getting the CRL from EZCA and posting it in that specific endpoint.

  5. Click Next. CRL Details

Issuance Policy

  1. Select the Certificate Template you want this CA to Issue. Leave as “Subordinate CA Template” unless creating a 1 tier PKI (Not Recommended) CA Root Certificate Template
  2. Enter the largest certificate lifetime that this CA can issue. EZCA automatically calculates the recommended maximum based on CA lifecycle best practices. CA Max Certificate lifetime
  3. Click Next. Next

Select Location

  1. Select the location where you want your CA to be created.
  2. Click Create Create CA for Azure IoT Edge

Download Certificate

  1. Once the CA is created download to certificate and push it to all your devices and Azure IoT Hub as a trusted root. Download CA Certificate

Creating the Intermediate CA for Azure IoT Edge

Getting Started

  1. Go to https://portal.ezca.io/
  2. Login with an account that is registered as a PKI Admin in EZCA.
  3. Navigate to Certificate Authorities. Azure CA Menu
  4. Click on the “Create CA” Create Subordinate CA in Azure
  5. Select Subordinate/Intermediate CA. Select CA Type
  6. Click Next

Entering CA Information

  1. Enter Common Name: This is the name of the CA how it will appear in the certificate.
  2. (Optional) Enter CA Friendly Name This is the name that will appear in the EZCA portal, by default we will use the Common Name
  3. (Optional) Enter the Organization The Organization field is an optional certificate field that usually has the company name.
  4. (Optional) Enter the Organization Unit The Organization Unit field is an optional certificate field that usually contains the unit that runs this CA (For example: IT or HR).
  5. (Optional) Enter the Country Code The Country Code field is an optional certificate field that identifies the country where this CA is located.
  6. Click Next. CA Details

Cryptographic Requirements

  1. Unless you have specific compliance or security requirements, leave the default cryptographic values for best security and compatibility. Crypto Details

Validity Period

  1. Select your Validity Period Learn more about Validity Period best practices
  2. Enter a Notification Email this email address (as well as the PKI Administrators) will get all the notifications for the lifecycle of the CA.
  3. Select the lifecycle action you want EZCA to take when expiry of the CA is approaching
  4. Select the percentage of lifetime of the certificate when you want EZCA to start taking Lifecycle actions. Lifecycle Details

CA Certificate Revocation List

  1. Select if you want this CA should issue a CRL (Highly recommended)
  2. Click Next. CRL Details

CA Certificate Revocation List Advance Settings

Changes to this section are only recommended for PKI experts with specific requirements.

  1. Click the expand button CRL Details
  2. Enter the desired CRL Validity Period in days
  3. Enter the desired CRL Overlap Period in hours
  4. (Optional) Enter the CRL endpoint where you will publish your CRLs

    Custom CRL endpoints are supported by EZCA by adding the CRL endpoint as the CRL endpoint in the certificate. However, your PKI admins are responsible from getting the CRL from EZCA and posting it in that specific endpoint.

  5. Click Next. CRL Details

Issuance Policy

  1. Change the certificate Issuing Template to “IoT Edge CA Template” Azure IoT Edge Certificate Authority Template
  2. Enter the largest certificate lifetime that this CA can issue. EZCA automatically calculates the recommended maximum based on CA lifecycle best practices.
  3. Click Next.

Select Location

  1. Select the location where you want your CA to be created. Create CA in Azure for Azure IoT Edge

Add Geo-Redundancy

EZCA Allows you to create multiple CAs across many regions to create Geo-Redundancy.

Each location will be charged as an extra Certificate Authority.

  1. Click the “Add Secondary Location” Button. Create Secondary Location
  2. Enter the Location information. Create Secondary Location
  3. Add as many locations as needed.

Create CA

  1. Click Create. Create CA

Chaining to EZCA Root CA

  1. Once the CA is requested, a Certificate Signing Request (CSR) will be created for each location. CSR Created
  2. If your desired Root CA is an EZCA CA, Select it from the dropdown and click create CA. CSR Created
  3. Repeat these steps for each location.
  4. Your CA is ready to be used!

Creating Device Certificate for Azure IoT Edge Devices

Once the CAs are created, we have to create a gateway device certificate for each device.

Creating Certificate Request in Azure IoT Edge Device

  1. SSH into your IoT Edge Device.

    These actions must be done on the IoT Edge Device since private keys should never leave the computer they were created on.

  2. Run the following command where
    1. PRIVATEKEY.key is the path to where you want to save the private key
    2. MYCSR.csr is the path to where you want to save the certificate signing request
    3. DEVICEID is the device ID for this IoT Edge device.
    openssl req -newkey rsa:2048 -keyout PRIVATEKEY.key -out MYCSR.csr -subj /CN=DEVICEID
  3. Once the CSR is created, we have to output it since we will use it to request the certificate in EZCA. 
    cat MYCSR.csr

Requesting the certificate in EZCA

  1. Navigate to https://portal.ezca.io/
  2. Navigate to Certificates.
  3. Click Create Certificate. Create new Certificate 1 Select the Azure IoT Edge Subordinate CA we created in the previous section. Select IoT Edge CA
  4. Enter your Device ID as the certificate subject name following this format: CN=DEVICEID where device id is the device ID of your IoT edge. CN Added for IoT edge device
  5. Copy the CSR we created in the IoT edge.
  6. Paste it in the CSR area. CSR Added
  7. Click the “Request Certificate” button Request Certificate for Azure IoT Edge Device
  8. Once the certificate is created, Download the file and save it in the IoT edge device in the same path as the PRIVATEKEY.key with a .pem file ending. Download IoT Edge Device Certificate

Next Steps

  1. Now you are ready to Configure certificates on the IoT Edge device