Create IoT Edge Gateway

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.

Creating the Root CA

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.
4. Click on the “Create CA”
5. Select Root CA.
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.

Cryptographic Requirements

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

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.

CA Certificate Revocation List

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

CA Certificate Revocation List Advance Settings

1. Click the expand button
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.

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)
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.
2. Click Create

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.

Creating the Intermediate CA

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.
4. Click on the “Create CA”
5. Select Subordinate/Intermediate CA.
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.

Cryptographic Requirements

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

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.

CA Certificate Revocation List

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

CA Certificate Revocation List Advance Settings

1. Click the expand button
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.

Issuance Policy

1. Change the certificate Issuing Template to “IoT Edge CA 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.

Add Geo-Redundancy

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

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

Create CA

1. Click Create.

Chaining to EZCA Root CA

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

Creating Device Certificate

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

Creating Certificate Request

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. 1 Select the Azure IoT Edge Subordinate CA we created in the previous section.
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.
5. Copy the CSR we created in the IoT edge.
6. Paste it in the CSR area.
7. Click the “Request Certificate” button
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.

Next Steps

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