# Edge Framework - FAQ
Why use Docker environment in the Edge?
Deploying modules as docker containers allows provides many benefits - Firstly, the isolation provided by docker ensures separation of workloads between themselves as well as with the host. Secondly, easy cloud first configuration and licensing is made possible. Lastly, updates to the docker images are easier to manage using cloud first principles.
Why do we need to have a Hardware based Root of trust?
Edge or a directly connected device is the first point of defense for industrial devices. Since an internet connection is always required, these devices are called internet facing devices which are susceptible for attempts to compromise the device. Hence it becomes very important to protect the identity and keys for such devices. Having a Hardware based root of trust (HRoT) outside the main CPU and operating system allows to protect the identity and keys in such an HRoT which means, even if the main OS and CPU are compromised, the keys are never compromised.
Why do we use X.509 certificate based mutual authentication. Why not use SAS Tokens or TPM Endorsement key based authentication?
SAS is a proprietary mechanism implemented by Microsoft and works only on Azure. Also, it needs frequent refresh of the token that can cause problems for devices with limited connectivity.
Another authenticate mechanism supported by DPS is the TPM Endorsement Key (Ek). Using this mechanism requires to individually whitelist the public Ek from each device in DPS and further, requires that any Edge or Connected device always contains a TPM. In practice, a HRoT can be TPM or another crypto chip. When a different crypto chip is used, the Ek based authentication mechanism cannot be applied.
X.509 based mutual authentication is widely accepted standard. It allows for binding the identities to certificates and future expansion based on upcoming standards such as IEEE 802.1AR
Why can't I use an IoT Hub that I setup by myself? Why should I use the Ability platform?
An IoT Hub is simply an ingestion cloud gateway that allows for authenticated communication with the devices. The value of the Ability platform is available in workloads after the IoT Hub. In simple terms, IoT Hub provides a secure tunnel for devices to communicate. The communication occurs over Ability Device API that allows the devices to utilize the full value of Industrial IoT.
Why do we prohibit modules from having direct internet connectivity?
The Edge architecture isolates the Internet connectivity from OT (Operations Technology) connectivity. Edge modules usually connect to devices in OT networks to act as bridge between these devices and Ability Platform. Providing direct internet connectivity to these modules would make them susceptible to attacks and attackers can use these modules to piggy back into the OT environment. Secondly, malware typically makes use of outbound internet connectivity to contact C&C servers. Centralizing the internet connectivity to Edge Proxy and whitelisting the outgoing connections allows us to have a verifiable security postured in the Edge.
A single module having access to both internal and external interfaces violates the "isolation" principles. A situation requiring such an access would require to split the module into an external facing and an internal facing counterparts as described in the factory proxy design
Why do we have V2Ray proxy? What does it do?
Outbound connections from Edge proxy are routed through V2Ray. Using V2Ray allows to configure allowlisted destinations such as DPS, IoT Hub and Container registry. Only allowlisted destinations in V2Ray are allowed for outgoing connections from the Edge proxy.
Why not use Azure IoT Edge? Why are we investing in developing our own Edge
The reason why we started developing our Edge initially was the non availability
of Azure IoT Edge. Later, in 2018, Azure IoT Edge was announced and upon
investigations, it was found that the security posture of Azure IoT Edge was not
acceptable for industrial environments.
There have been multiple discussions with Microsoft on converging our Edge
activities with Microsoft Azure ioT Edge. Microsoft philosophically agrees about
the raised concerns (More details
here
is a bit outdated. A fresh review might be needed) However, the situation during
early 2020 was that Microsoft Azure IoT edge is still not in an acceptable
security posture to start using it for industrial purposes.
Is using TPM mandatory? Am I free to use a hardware based root of trust of my own choice?
ABB's MCSR requires that secrets are protected in an HRoT. TPM has been used in Ability Edge and recommended since:
- TPM is based on accepted TCG standards
- Irrespective of the TPM manufacturer, the interfaces and functionality will be same
- Availability of commercial grade stack and software (Mocana). Using Mocana along with TPM is advantageous as it allows us (Businesses) to achieve a FIPS-140-2/3 certification with less effort
- Availability of open source stack (TSS)
- Capability of disabling algorithms during the TPM life time and firmware upgrades that can introduce new algorithms
However, TPM is not mandatory. Any HRoT that allows to generate Private keys with sufficient entropy and ensures that the private keys never leave the silicon along with capabilities to realize a secure storage functionality in the devices would be acceptable. Of course, such choices must be reviewed and agreed by the cyber security management of the divisions and possibly Group Cyber Security Council.
Are there any edge components that can be re-used in other ABB products that need edge capabilities?
Yes, a number of components of ABB Edge technology are available for reuse into different solutions and products.
- The Ability Edge security component “Device provisioning and Certificate Management” service provides device certificates and the management and renewal workflows. These certificates can be used for Device identity for ex- ample, while interfacing with ABB Ability™ Platform.
- The ABB Ability™ Edge security component “Secure Storage” provides abstraction over TPM chip implementation and this can be used for secure connection using TLS.
- Edge components like the “MQTT Broker”, “Edge Agent/Proxy” and“Router” are framework components that enable running container images of Business applications, this includes installation, provisioning and the communication with ABB Ability™ Cloud platform.
Why do we need to use Docker Swarm?
Docker Swarm was introduced mainly due to the availability of "secrets" in Swarm. The Edge modules need to be provisioned with credentials for connection to the broker. Secrets are used to inject the credentials at run time and to use the secrets feature.
Secrets are also available in other container orchestration tools like Kubernetes, but its minimal requirements were too high (mostly because of RAM) for small factor Edge devices.
With advent of "lighter" versions of Kubernetes (like K3s) and problems experienced with Docker Swarm (corrupted network configuration after restart) the replacement of Docker Swarm is being evaluated.
# Edge Agent Upgrade - FAQ
What are the steps for upgrading Edge Proxy to Edge Agent?
Update the Edge device configuration model with the image for the Edge Agent using the Information Model API.
For Example:
NOTE-The above screenshot is only a snippet of the sample configuration model
Additionally, The bootstrap image in the edge.env file available in /var/ability/config path must be updated to the Agent image, which was updated in the Edge configuration model EDGEPROXYIMAGE=abbability.azurecr.io/edge/agent:22.4.1.1
Please refer to the Edge Software page for details on the latest software available.
What are the supported module and device API versions in the new C#Agent?
The C#Agent supports both apiVersion V1 and V2 for device and module APIs; however, device apiVersion V1 will be deprecated by the end of Q4'22, hence it is recommended to migrate to apiVersion V2 as soon as possible. In the meantime, while the module developers prepare to use apiVersion V2, there is an intermediate version (referred to as apiVersion V1.5 ) which would allow the modules to use apiVersion V1 while the device & cloud platformcommunicates with apiVersion v2. To enable api version V1.5, please set the following attributes in the Edge configuration type as shown below.
properties►systemModules►Edge-proxy►configuration►apiVersion to v1
properties►systemModules►Edge-proxy►configuration►feature►EdgeSecrets to true
NOTE-The above screenshot is only a snippet of the sample configuration model
Is it possible to enable Edge Secrets feature while Edge Agent uses module apiVersion V1?
Yes, it is possible to enable Edge Secrets while Edge Agent uses module API Version V1.
To enable Edge Secrets while Edge Agent uses module apiVersion V1, please set the following attributes in the Edge configuration type as shown below.
properties►systemModules►Edge-proxy►configuration►apiVersion to v1
properties►systemModules►Edge-proxy►configuration►feature►EdgeSecrets to true
For Example:
NOTE-The above screenshot is only a snippet of the sample configuration model
Also, for Edge Secrets to work, Swarm Autolock is necessary, which can be enabled by following the steps here.
Any new Edge provisioned after making the above changes to the type would start up with Module apiVersion V1, Device apiVersion V2, and the Edge Secrets feature enabled if the Edge Agent image is used.
The Edge Secrets feature is not supported with Edge Proxy (nodeJS version).
What is the supported software stack for using Edge Agent?
The software stack needed to run Edge Agent is listed below.
The following software represents the Edge packages required for amd64 hardware with TPM 2.0 support.
| Package | Ubuntu 18.04 Version | Ubuntu 20.04 Version |
|---|---|---|
| abb-edge-installer | 2.4.0 | 2.4.0 |
| sec-cmsn-tpm20 | 3.2.8-1 | 3.2.8-1 |
| sec-dcmsn-tpm20 | 3.2.8-1 | 3.2.8-1 |
| sec-lib-tpm20 | 3.2.8-1 | 3.2.8-1 |
| sec-svc-tpm20 | 3.2.8-1 | 3.2.8-1 |
The following software represents the Edge packages required for armhf, Raspberry Pi, hardware with TPM 2.0 support.
| Package | Ubuntu 18.04 Version | Ubuntu 20.04 Version |
|---|---|---|
| abb-edge-installer | 2.4.0 | 2.4.0 |
| sec-cmsn-tpm20 | 3.2.8u18.04-1 | 3.2.8-1 |
| sec-dcmsn-tpm20 | 3.2.8u18.04-1 | 3.2.8-1 |
| sec-lib-tpm20 | 3.2.8u18.04-1 | 3.2.8-1 |
| sec-svc-tpm20 | 3.2.8u18.04-1 | 3.2.8-1 |
NOTE-The above screenshot is only a snippet of the sample configuration model
What are the other changes that a module developer needs to be aware while upgrading to apiVersion V1.5 (i.e., apiVersion V1 + Edge Secrets) or V2?
Below are some of the changes that a module developer needs to know before upgrading to V1.5 (apiVersion V1 + Edge Secrets) or V2.
The
targetheader property that used to allow passing extra user data (ex:module1/connectedDevice1/userData123) can only contain a valid principal now(ex: "module1/connectedDevice1"). The module developer can use a new property calledcontextin the header to pass additional user data.When a "model.create" request is sent for a
device model, this request creates the requested device model, any related configuration model, and also creates an implicit subscription for the configuration model; however, a "ObjectModel.Created" notification for the device model is no longer sent.When a "model.delete" request is sent for
device model, this request deletes the requested device model and also deletes the implicit subscription for the configuration model; however, a "ObjectModel.Deleted" notification for device model is no longer sent as a result, any persisted device and configuration model related to the deleted object is not cleared from the MQTT database on the device.The environment variables set in
properties.docker.envof the module configuration model as well asproperties.globalEnvironmentVariablesof the Edge configuration model are case-insensitive. For example,http_proxyandHTTP_PROXYare treated as duplicate keys, which will result in docker service creation failure. More details regarding the management of configuration values in .NET are available here.The common volume mount
/sharedFileswhich was available while using the nodeJS proxy version, has been deprecated as per the Cyber Security recommendation. Alternatively, the file-sharing feature of Edge Agent can be leveraged to transfer files between modules. More details are available here.
What are the steps for enabling Device API Version V2 while upgrading from Edge Proxy to Edge Agent?
Update the Edge Configuration Type using the Type Definition Registry API to include a new section called apiVersion under the path
properties►systemModules►Edge-proxy►configuration►apiVersion
"configuration": {
"apiVersion": {
"description": "api version and mqtt topic version to be used, v1 or v2",
"dataType": "string",
"value": "v2"
}
}
For Example:
NOTE-The above screenshot is only a snippet of the sample configuration model
Any new Edge provisioned after making the above changes to the type would start up with apiVersion V2 if the Edge Agent image is used.
For any existing Ability Edge that is running on a proxy, follow the steps in Q.1 to update the image in the Edge Configuration Model after updating the type to include the new property section called apiVersion.
For Example:
NOTE-The above screenshot is only a snippet of the sample configuration model
At any given time, Ability Edge will support either V1 or V2 only, based on the configuration.
Important: During the upgrade from Edge Proxy to Edge Agent, if the choice is made to use the Device API Version V2, then the update of Edge Module images with changes to support API Version V2 needs to be done simultaneously.
What are the steps to enable Edge Secrets while using apiVersion V2?
Edge Secrets can be enabled by updating the Edge Configuration Type using the Type Definition Registry API to include a new section called apiVersion under the path properties►systemModules►Edge-proxy►configuration►feature►EdgeSecrets
Please note that the apiVersion needs to be set to V2 as explained in Q.2.
"configuration": {
"apiVersion": {
"description": "api version and mqtt topic version to be used, v1 or v2",
"dataType": "string",
"value": "v2"
},
"feature": {
"EdgeSecrets": {
"dataType": "boolean",
"value": true,
"isMandatory": false
}
}
}
For Example:
NOTE-The above screenshot is only a snippet of the sample configuration model
Any new Edge provisioned after making the above changes to the type would start up with API Version V2 and the Edge Secrets feature enabled if the Edge Agent image is used.
# Enabling Swarm Autolock
Please note that, apart from the above change, the Edge Security packages need to be updated to enable the Edge Secrets feature. This is needed to enable the Swarm autolock feature, which stores the unlock key in the TPM. Steps to be followed:
1) Upgrade security packages to 3.1.1 or above
○ Download security package version 3.1.1 or above to the target machine
○ Upgrade security components using the command `apt install ./sec*`
2) Upgrade installer to version 2.3.1
○ Download installer 2.3.1 to the target machine
○ Upgrade installer using the command `apt install ./abb-edge-installer_2.3.1_all.deb`
3) Enable swarm autolock
○ Run 'abb-iot-edge-enable-swarm-autolock`
Now the swarm autolock is enabled in your machine, and the unlock key is stored in the TPM. On every docker restart, a key will be extracted from TPM and a swarm unlock will be done.
NOTE-The above screenshot is only a snippet of the sample configuration model
How does the Module API topic names differ while using the Edge Agent on V2 when compared with Edge Agent on V1 (or Edge Proxy)?
The list of Module API topics supported on V1 and its equivalent on V2 are as follows:
| # | Purpose | V1 Topic Name | V2 Topic Name |
|---|---|---|---|
| 1 | Sending TimeSeries data | modules/<module_id>/messages/events/type=timeSeries | from/module/{module_id}/variable |
| 2 | Sending Alarm data | modules/<module_id>/messages/events/type=alarm | from/module/{module_id}/alarm |
| 3 | Sending Event data | modules/<module_id>/messages/events/type=event | from/module/{module_id}/event |
| 4 | Device Creation | modules/<module_id>/messages/events/type=deviceCreated&objectId= | from/module/{module_id}/action/model/create&objectId={objectId}&ack=all&correlationId= |
| 5 | Device Update | modules/<module_id>/messages/events/type=deviceUpdated&objectId= | from/module/{module_id}/action/model/update&objectId={objectId}&model= |
| 6 | Device Delete | modules/<module_id>/messages/events/type=deviceDeleted&objectId= | from/module/{module_id}/action/model/delete&objectId={objetId}&ack=all&correlationId= |
| 7 | Model Query | modules/<module_id>/messages/events/type=modelQuery&ack=all&id= | from/module/{module_id}/action/model/query&ack=all&correlationId= |
| 8 | File Upload | modules/<module_id>/files/upload&Id= | from/module/{module_id}/action/file/upload&correlationId= |
| 9 | Method Invocation | modules/{module_id}/methods/req/{methodName}/{requestId} | to/module/{module_id}/action/method/invoke&method={method_name}&requestId={requestId}&objectId=objectId&model=model |
There are additional actions supported in API Version V2. The full specification is available here:
- Edge Module API v2 specification Import into AsyncAPI playground
- Documentation in ADP is available here
- Sample Reference Types can be referred here