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.

Before You Start¶

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 and deviceSecret. 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 and productSecret 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 `Lifetime`. `Lifetime` is counted in seconds and the value range is 30 to 86400.
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 `Lifetime`. `Lifetime` is counted in seconds and the value range is 30 to 86400.
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.