CoAP-based Connection and Communication¶
EnOS supports CoAP-based connection and communication. The CoAP protocol is suitable for resource-limited and low-power devices, especially NB-IoT devices. This topic describes the CoAP-based connection process with DTLS.
Connection Process¶
The process for connecting NB-IoT devices to EnOS via CoAP is shown as per the below.
Obtain the product key and product secret by creating a model and a related product in EnOS.
Create a device in EnOS. For a device that uses unique-certificate-per-product authentication, obtain its device secret.
Configure the authentication keys on the device based on one of the authentication methods below.
For unique-certificate-per-device authentication, configure the product key, device key, and device secret.
For unique-certificate-per-product authentication, configure the product key and device key.
Power on the device and get the device online.
The device initiates a handshake request.
EnOS confirms the request and completes the handshake. A secure message channel is established.
(Optional) For devices that use unique-certificate-per-product, the device sends a request to EnOS to query the device secret.
(Optional) EnOS sends a response to the device with the device secret included in the response.
The device uses the product key, product secret, and device secret to initiate authentication.
The device is authenticated and activated on EnOS.
EnOS sends a CoAP ACK message to the device.
Prerequisite¶
Depending on the authentication method, you need complete the appropriate configurations in EnOS and obtain the required keys for authentication:
For unique-certificate-per-device authentication, register devices one by one and obtain their
productKey
,deviceKey
anddeviceSecret
. For information about how to register a device, see Registering a Device.For unique-certificate-per-product authentication, create a product that the device belongs to and obtain the
productKey
andproductSecret
of the device. For information on how to create a product, see Creating a Device Collection (Product). For the devices authenticated with unique-certificate-per-product authentication, enable Dynamic Registration.
For more information about device authentication, see Device and Cloud Security.
Connecting to the CoAP Server¶
The IP address of the CoAP server is coap-<hostname>
, where the hostname
is where EnOS is located. For example, if EnOS is located on abc.def.com, then the CoAP server address would be coap-abc.def.com.
Establishing the DTLS Secure Channel¶
The Pre-shared Key (PSK) is used as the key exchange algorithm to establish a secure channel. The Cipher Suites that EnOS CoAP server supports include the following:
TLS-PSK-WITH-AES-128-CCM-8
TLS-PSK-WITH-AES-128-CBC-SHA256
Unique-certificate-per-device Authentication¶
The PSK used by devices during DTLS handshake is as follows.
identity:{ProductKey},{DeviceKey},{SecureMode},{Lifetime}
Key:SHA-256({DeviceSecret}) Byte 9 to Byte 24 (16 bytes in total)
Parameter |
Description |
---|---|
ProductKey |
The product key used for authentication. |
DeviceKey |
The device key used for authentication. It should be unique within an organization (OU). You may use the IMEI of an NB-IoT device as its device key. |
SecureMode |
SecureMode is set as 2 for unique-certificate-per-device authentication. |
Lifetime |
Used to determine the online status of device. A device would be determined offline if it does not exchange any message with EnOS within the period specified by |
DeviceSecret |
The device secret used for authentication. |
Sample PSK parameters:
Identity: MuGsF6W4,15bBZlRknc,2,3600
Key: 0x01 0x24 0xDD 0xA7 0xA5 0xC6 0x3F 0x92 0xD9 0x8C 0x2F 0x80 0x9B 0x1E 0x3C 0x36
Unique-certificate-per-product Authentication¶
The PSK used by devices during DTLS handshake is as follows.
identity: {ProductKey},{DeviceKey},{SecureMode},{Lifetime}
Key: SHA-256({ProductSecret}) Byte 9 to Byte 24 (16 bytes in total)
Parameter |
Description |
---|---|
ProductKey |
The product key used for authentication. |
DeviceKey |
The device key used for authentication. It should be unique within an OU. You may use the IMEI of an NB-IoT device as its device key. |
SecureMode |
SecureMode is set as 3 for unique-certificate-per-device authentication. |
Lifetime |
Used to determine the online status of device. A device would be determined offline if it does not exchange any message with EnOS within the period specified by |
ProductSecret |
The product secret used for authentication. |
Sample PSK parameters:
Identity: MuGsF6W4,15bBZlRknc,3,3600
Key: 0x01 0x24 0xDD 0xA7 0xA5 0xC6 0x3F 0x92 0xD9 0x8C 0x2F 0x80 0x9B 0x1E 0x3C 0x36
After the handshake is completed, the device should query the device secret by sending a request. The request format is:
GET /topic/ext/session/{productKey}/{deviceKey}/thing/activate/info
The response to this request includes the device secret:
Code: CoAP return code. Refer to CoAP protocol documentation.
Payload: {
"id": {id},
"version": "1.0",
"method": "thing.activate.info",
"params":{
"assetId": {assetId},
"productKey": {productKey},
"deviceKey": {deviceKey},
"deviceSecret": {deviceSecret}
}
}
Parameter |
Description |
---|---|
id |
The unique identifier of a message. |
assetId |
The asset identifier of the device. |
After the deviceSecret
is obtained, the device would be authenticated via productKey
, deviceKey
, and deviceSecret
when it tries to connect to EnOS.