CoAP Overview

The CoAP Endpoint coap://coap.os.1nce.com:5683 hosts a POST endpoint on the server root path (/). The endpoint supports both normal, non-translatable messages and translatable messages by using the energy saver.

The POST endpoint takes an optional query parameter (or Location-Query) t to provide the MQTT topic used for forwarding this message to a MQTT broker (e.g., coap://coap-service:5683/?t=topicName\). The Location-Query is limited to 255 characters by the CoAP protocol, hence the topic name itself can only contain up to 253 characters (t and `= also count as characters). The topic name itself can only contain alphanumeric characters, underscores, and forward slashes (no two slashes in a row). If these constraints are violated, a bad request (4.00) will be returned.

If a targeted device could not be found or is in a non-active status, the CoAP service will return an unauthorized (4.01) and no further processing of the message will take place.

CoAP Communication

While using UDP protocol for transport, the CoAP protocol offers reliable communication by using message confirmation mechanism. Each CoAP request has to be acknowledged by the server, so that the client would be sure that the message was processed:

There are few key moments that allow reliable communication:

1. To maximize the chance that the message succeeds even in the lossy network environment, CoAP has a retransmission mechanism. The client would re-send the Confirmable message (CON) until the Acknowledgement (ACK) is received or the exchange lifetime has ended. The total exchange lifetime (EXCHANGE_LIFETIME) is the time from starting to send a Confirmable message to the time when an acknowledgment is no longer expected.
   By default, the EXCHANGE_LIFETIME value is 247 seconds.
2. CoAP Messages contain Message ID (also known as MID) to detect duplicates due to retransmissions. The Message ID has to be unique during the EXCHANGE_LIFETIME, so the client's endpoint should be able to specify a unique MID value if messages are being sent often enough. Most high-level CoAP clients are managing MID uniqueness internally, but for low-level clients like modem Quectel BG95, it can be specified in the AT command as msgID[2]:

AT+QCOAPHEADER=<clientID>,<msgID>,<mode>[,<TKL>,<token>]

There are two examples of the retransmission situation in a single exchange lifetime:

• client's CON message did not reach the server. The client is resending the same CON message with the same MID.
• server's ACK message did not reach the client. The client is resending the same CON message with the same MID (because there was no acknowledgment). The server is answering with the same ACK because it sees the already processed MID and does not process the request again.

DTLS encryption for CoAP

Ensuring, data is securely sent from a device to 1NCE OS, it is an important part of gaining the trust of customers with their data. To be able to provide this secure connection 1NCE OS has implemented a DTLS layer in the CoAP communication from the device to 1NCE OS. This allows the device to securely send its data to 1NCE OS without the possibility of messages being read or modified along the way. The picture above describes this process. First, when the device is ready to onboard itself, it will call the CoAP bootstrapping endpoint. This will retrieve the necessary DTLS info to onboard itself securely and initialize the CoAP connection using a PSK.

Features & Limitations

DTLS as a security protocol provides secure and fast data streaming. This comes with some advantages but also has some limitations. Below these key points are explored in the context of a CoAP connection.

Features

DTLS is able to provide datastreaming functionality to devices with a low delay compared to TLS. It is able to provide this because it preserves the semantics of the underlying transport. DTLS also has advanced security. As a result, communication between client-server applications cannot be eavesdropped on or tampered with. This ensures that the streamed data is the same data as it was received.

DTLS makes use of the UDP protocol for this functionality. The data is sent in a fire and forget style, so no handshakes occur, and the message is sent without any reception or delivery confirmation. UDP also avoids the TCP meltdown problem, where different transport layers compensate for each other, cause delays in the data transfer.

Limitations

The main limitation of DTLS is the use of the UDP protocol. The major drawbacks of using UDP are, having to deal with packet reordering, loss of datagram, and data larger than the size of a datagram network packet.

Encryption Key

To use DTLS, an encryption key is required to ensure security. For 1NCE OS, a pre-shared key is used to encrypt and decrypt the data. For connecting a device with secure CoAP with DTLS encryption the endpoint coaps://coap.os.1nce.com:5684 can be used. This endpoint allows to specify a pre-shared key manually or use our bootstrapping endpoint to generate a pre-shared key coap://coap.os.1nce.com:5683/bootstrap.

Example

Below is an example of retrieving the pre-shared key and client identity. First, a request is done to the CoAP bootstrapping endpoint, this request will result in the following CSV object:

preSharedKey,clientIdentity,coapsEndpointUrl

The following piece of code is used to process the shown above response, so the device is fully onboarded with credentials and ready to send messages. In the security parameters object the clientIdentity and preSharedKey will be set and these parameters will be passed to the CoAP DTLS client.

const coapDtls = require("node-coap-client").CoapClient;

async function coapPostDtls(clientIdentity, preSharedKey, postPayload) {
  
  const securityParameters = {
    psk: {
      [clientIdentity]: preSharedKey,
    },
  };
  coapDtls.setSecurityParams(coapsUrl, securityParameters);
  try {
   const result = await callPost(coapDtls, coapsUrl, postPayload);
   return result;
  } catch(e) {
    return e;
  }
}

In the following snippet, the initialized client will be used to send a message.

const coapDtls = require("node-coap-client").CoapClient;

async function callPost(client, url, postPayload) {
  console.log("Calling: ", url);
  try {
    const pingSuccess = await client.ping(url /* string | url | Origin */, [
      2000,
    ]);
    if (!pingSuccess) {
      console.log("Ping request failed");
      throw Error(`Ping to ${url} failed`);
    } else {
      console.log("Ping successfull");
    }
    const res = await client.tryToConnect(url);
    console.log("Connection attempt result: ", res);
    if (res) {
      const payload = Buffer.from(postPayload);
      const options = {
        /** Whether to keep the socket connection alive. Speeds up subsequent requests */
        keepAlive: true,
        /** Whether we expect a confirmation of the request */
        confirmable: confirmable,
        /** Whether this message will be retransmitted on loss */
        retransmit: false,
      };
      const result = await client.request(
        url /* string */,
        "post" /* "get" | "post" | "put" | "delete" */,
        payload /* Buffer */,
        options /* RequestOptions */
      );
      result.code = result.code.toString();
      printResponseHeaderBody(result);
      const resultObj = generateResponseObject(result.code, result.payload.toString());
      if (result.code !== "2.04") {
        
        throw new Error(resultObj);
      }
      return resultObj;
    }
  } catch (error) {
    console.log("Coap Error ", error);
    throw error;
  }
}

function generateResponseObject(respCode, body) {
  return {
    code: respCode,
    message: body,
  };
}

CoAP Endpoint Information

Base URL: coap.os.1nce.com
Protocol: CoAP(s)

Responses

DTLS Bootstrapping Information

Information model:

The pre-shared key is valid indefinitely. If the bootstrapping is called 5 or more minutes after the last time bootstrapping was called, the pre-shared key will be regenerated with a new value.

UnauthorizedResponse

API responses when the Terms of Use and Data Processing Agreement are not accepted for the owner of the device:

ServerSideErrorResponse

API response in case of server-side errors: