Introduction
When IoTEdge acts as a transparent gateway, EdgeHub inside IoTEdge gateway requires a server certificate so that IoT Devices and Azure modules running inside the IoTEdge gateway can talk in a secured fashion. This EdgeHub certificate is signed by a Device CA.
IoTEdge runtime expects Device CA certificate, Device CA private key and the full chain of upstream certificates used to sign the Device CA certificate in its configuration file.
To know more about how certificates are used in Azure IoT, click here.
The following sections cover certificate creation, upload, renewal, and management use cases.
IoT Edge Signing Certificate Upload
Users can upload a Root/Intermediate CA certificate as part of the project's Azure policy. This certificate can be used to sign "device CA certificates" for all the edge nodes running IoTEdge Runtime Application in that project.
- Step 1 > In the create project screen, select 'Azure' as a profile.
- Step 2 > Click on the 'Attach Certificate for leaf device or edge module communication' checkbox.
- Upload Root/Intermediate CA certificate, an Intermediate CA key, and password if required.
- Step 3 > After the project creation process is complete, you could click on the project list, and the Azure project will open in a new temporary tab. The last field in the details section shows 'Yes' for the 'Attach Certificate for leaf device or edge module communication?' option. If you click on the expand (
) icon on the right side, the certificate's details for this project could be seen below. Information like Valid from, Valid Till, Issuer Details, Serial number, Signature algorithm, etc., are shown for the certificate. The certificate content also can be seen in this section.
Device CA Certificate Generation
- Step 1 > User deploys Azure IoT Edge application instance(s) on an edge node(s). The user initiates deployment either individually or as part of auto-deployment using the 'App Policy' in a project.
- Step 2 > User can indicate to ZEDEDA Cloud if it wants ZEDEDA Cloud to generate Device CA certificates by using specific system variables in cloud-config. Please refer to <insert link here> about the general use of system variables in the edge application's custom configuration.
- "$webhook.azure.iotedge.device_cert_required"
IoTEdge runtime will expect a Device CA certificate if this flag is set to true.
-
- "$webhook.azure.iotedge.gen_device_cert"
Generate device CA certificate signed by root or intermediate CA certificate.
-
- "$webhook.azure.iotedge.gen_device_key"
Generate private key for device CA certificate.
ZEDEDA Cloud generates a 'Device CA Certificate' pair signed by 'IoTEdge Signing Certificate'.
- Step 3 > ZEDEDA Cloud includes Device CA Certificate, Device CA Key generated in previous step and public part of IoTEdge signing certificate in the cloud-config and sends it to EVE-OS.
- Step 4 > The edge application instance (Azure module) detailed view shows the details of the Device CA certificate in use.
Certificate Renewal
The use cases mentioned in the next section trigger the certificate renewal process. The following are the steps to renew the certificate:
- Step 1 > The user sees the expiry message on the ZEDEDA GUI and clicks on the 'Update Certificate' button on the project details page.
- Step 2 > The certificate manager takes that command and sends a request to the Device CA service for a new certificate.
- Step 3 > The Device CA sends a renewed CA certificate to the certificate manager.
- Step 4 > The certificate manager queries external KeyStore, extracts metadata for that certificate, and stores it in the appropriate database. The certificate manager also saves the key and certificate in a secure store.
- Step 5 > The certificate manager then sends the device CA (Public + Private) keys to the concerned edge node(s) on which the Azure module has been deployed.
After the edge node receives the new keys, both the project and the edge applications (deployed because of the project application policy) start showing the renewed certificate.
Certificate Management Use Cases
The following are the scenarios where the certificate has to be renewed:
The Device CA Certificate is About to Expire
When the intermediate certificate is due to expire or has already expired, notifications messages are displayed on the following pages:
- Project detail view
- Application Instance detail view
The Device CA Certificate has Expired
When the Device CA certificate expires, The certificate manager notifies the same to the ZEDEDA Cloud The project detail view shows a notification 'The CA certificate has expired.' All the application instances deployed as part of the application policy in this project show an error in the application instance detail view.
The Intermediate Certificate Expiry
The device certificate is generated in ZEDEDA Cloud using the intermediate certificate. Depending on whether the intermediate certificate is about to expire or already expired, the following messages are displayed under the 'Status' tab of the edge application instance details screen.
- About to Expire
- Already Expired
IoT Edge Signing Certificate Expiry
The following are the steps to upload a new IoT Edge Signing Certificate when the already present IoT Edge Signing Certificate is about to expire.
- Step 1 > ZEDEDA Cloud certificate manager monitors the metadata of the certificates.
- Step 2 > It triggers action 30 days ahead of expiration:
- It generates a new certificate.
- It notifies ZEDEDA Cloud microservice responsible for using the certificate.
- User microservice figures out all the application Instances signed by this intermediate certificate and maintains this information for all the App Instances.
- Step 3 > The ZEDEDA GUI polls for an application instance, ZEDEDA Cloud indicates that certificate expiry is coming up, and the ZEDEDA GUI prompts an update/refresh with a new certificate.
- Step 4 > When a customer updates, ZEDEDA Cloud repeats the process with the new 'IoT Edge Signing Certificate'.
Compromised Intermediate Certificate
The following are the steps to upload a new intermediate certificate when the already present intermediary certificate is compromised.
-
Step 1 > The user uploads a new intermediate CA certificate and re-generates the device CA certificate with this new Intermediate CA certificate for all the edge nodes running the IoT edge runtime application.
-
Step 2 > The user uploads the Intermediate CA certificate in the project configuration.
-
Step 3 > ZEDEDA Cloud prompts the user to perform a force update of the application instance(s) for the given project.
-
Step 4 > Upon performing force update,ZEDEDA Cloud creates new user data with a newly generated Device CA certificate for the application Instances and notifies EVE-OS to purge and restart the application Instances.
Compromised Device CA Certificate
The following are the steps to upload a new device CA certificate when the already present device CA certificate is compromised.
-
Step 1 > The user regenerates the Device CA certificate and pushes it to the edge node.
-
Step 2 > Click on “Purge and Refresh” from the application Instance action menu.
-
Step 3 > ZEDEDA Cloud automatically regenerates the device CA certificate at every 'Purge and Refresh'.
-
Step 4 > ZEDEDA Cloud creates new user data with the newly generated Device CA certificate and pushes it to EVE-OS to purge and restart the application instance.
Note: Upon every purge or force update, ZEDEDA Cloud performs the following actions in the order specified:
-
Fetch the updated details from the edge application (if any)
-
Regenerates the user data (Certificate regeneration, if configured)
-
Issues purge operation for the purgeable drives (Volumes)