COAP protocol Note [RFC7252]

1. What is CoAP

"The Constrained application Protocol (CoAP) is a specialized web transfer Protocol for use with Constrained nodes and con Strained networks in the Internet of things. The protocol is designed for Machine-to-machine (ATM) applications such as smart energy and building automation. "

2. Features

• Rest-based architecture : Servers make resources available under a URL, and clients access these resources using methods such as GET, PUT, POST, and DELETE.
• UDP Binding with reliability and multicastsupport.
• Secure:default Choice of DTLS (Datagram Transport Layer Security) parameters is equivalent to 3072-bit RSA key.
• Asynchronous message exchanges.
• Simple proxy and caching capabilities.
• Optional observation[RFC7641] and block transfer[draft-ietf-core-block-19-block-wise Transfers]

3. Protocol Overview 3.1 A Two-layer approach

CoAP messaging layer used to deal with UDP and the asynchronous nature of the interactions.

Request/response interactions using Method code and response code.

3.2 Messaging Model

Reliability is provided by marking a message as confirmable (CON) message.

A message that does not require reliable transmission can be sent as a non-confirmable message (Non).

3.3 Request/response Model

CoAP Request and response semantics is carried in CoAP messages, which include either a Method Code or Resp Onse Code.

Request method Code has get, POST, PUT, DELETE four kinds.

Response has piggybacked Response, separate Response, non-confirmable Response.

4. Format

Version (Ver): 2-bit unsigned integer. Implementations of this specification must set this field to 1 (in binary).

Type (T): 2-bit unsigned integer. Indicates if this message is of type confirmable (0), non-confirmable (1), Acknowledgement (2), or Reset (3) .

Token Length (TKL): 4-bit unsigned integer. Indicates the length of the Variable-length Token field (0-8 bytes).

Code: 8-bit unsigned integer, split into a 3-bit class (most significant bits) and a 5-bit detail (least significant bits). Generally written in c.dd form, you can refer to CoAP Code registries.

Message ID: 16-bit unsigned integer in network byte order. Used to match messages of type Acknowledgement/reset to messages of type confirmable/nonconfirmable.

Token: Used to match a response with a request. [0-8bytes].

option: A list of options (in option number) that can be carried in Coap mesage. Each option consists of the following:

Option Delta: 4-bit unsigned integer. A value between 0 and 12.

If option Delta = = 13, then the option Delta (Extended) section is 1 byte,option delta = 13+option Delta (Extended)

If option Delta = = 14, then the option Delta (Extended) section is 2 byte,option delta = 14+255+option Delta (Extended)

Option Delta = = 15 is invalid.

Option Length: 4-bit unsigned integer. A value between 0 and 12.

If option length== 13, then the option Length (extended) portion is 1 byte,option length= 13+option Length (Extended)

If option length== 14, then the option Length (extended) portion is 2 byte,option length= 14+255+option Length (Extended)

Option Delta = = 15 is invalid.

the calculation of Option number:

Option number is obtained from the option delta. The option number is calculated by simply summing the Option Delta values of this and all previous options before it. That is to say The option number for an option is the value that it has previously all option delta and its own option delta add up.

5. Message Transmission

There are four types of messages: confirmable (0), non-confirmable (1), Acknowledgement (2), or Reset (3).

5.1 Messages transmitted reliably

• This type can be used with confirmable (CON) message,request and response.
• After receiving confirmable (CON) message There are two options, (a) Back to acknowledgement message (b) Reject the message.
• If you want to reject the confirmable (CON) message, send a reset (RST) message, and then ignore the message.
• Re-transmit. UDP is unreliable and sender confirmable (CON) message relies on a timeout and a retransmission counter to determine the retransmission time.

5.2 Messages transmitted without reliability

• This type can be used by both request and response.
• No need to return to acknowledgement.
• If you want to reject non-confirmable (NON) message, send a reset (RST) message, and then ignore the message.

The following is a summary of the use of Mesage type:

* Indicates that it is not a normal operation, just to cause the other party to return reset message (CoAP ping).

6. request/response6.1 Requset

• CoAP supports the basic methods of GET, POST, PUT, and DELETE.

6.1.1 Method Code

• Get: Gets the resources on the server. Server may return to 2.05 (Content) or 2.03 (Valid) Response Code.
• POST: Typically used to create new resources or update resources. If the resource has been created, the server returns 2.01 (Created) Response code; If Psot succeeds but the server does not create the resource, the server returns 2.04 (Changed) Response code If the post succeeds in causing the target resource to be deleted, the server returns 2.02 (Deleted) Response Code.
• PUT: Update the resources on the server. If the resource exists, back to 2.04 (Changed) Response code, or if the resource does not exist, the server may create a resource back to 2.01 (Created) Response code. If the resource cannot be created or modified, the error Response back.
• Delete: Deletes the resource on the server. Back to 2.02 (Deleted) Response Code.

6.2 Response

　 There are three types of piggybacked Response, separate Response, non-confirmable Response .

• Piggybacked Response. The most commonly used type, reponse content is placed directly in the acknowledges.
• Separate Response. The server is temporarily not able to go directly back (may require more time to prepare), directly back to empty acknowledgement. When the server is ready, the client is sent a confirmable message (or non-confirmable message), and the client returns to acknowledgement. If the server receives a client retransmission before replying to clinet, it also goes back to empty acknowledgement.
• Non-confirmable Response. The client sends out non-confirmable Message,server generally also non-confirmable message back. spec says server can also send confirmable MESSAGE[P14].

Examples of three response types:

You can see that when the server returns to separate response, token is the same token as the client's request, but the message ID has been changed.

6.2.1 Response Code

• success:2.xx
• Client error:4.xx
• Server error:5.xx

Success 2.xx

• 2.01 Created. Reply to post or put.
• 2.02 Deleted. Reply to delete, in some cases post.
• 2.03 valid.indicate that the response identified by the Entity-tag identified by the included ETag Option is Valid. So, Resp Onse must take ETag Option.
• 2.04 Changed. Reply to post and put.
• 2.05 Content. Reply Get.

Client Error 4.xx

• 4.00 Bad resuest.
• 4.01 Unauthorized
• 4.02 Bad Option
• 4.03 Forbidden
• 4.04 not Found
• 4.05 Method not allowed
• 4.06 not acceptable
• 4.12 Precondition Failed
• 4.13 Request Entity Too Large
• 4.15 Unsupported Content-format

Server Error 5.xx

• 5.00 Internal Server Error
• 5.01 not implemented
• 5.02 Bad Gateway
• 5.03 Service Unavailable
• 5.03 Service Unavailable
• 5.05 proxying not supported

7. Options 7.1 Option Numbers

The different option has different option number to represent.

Critical = (Onum & 1);
UnSafe = (Onum & 2);
Nocachekey = ((Onum & 0x1e) = = 0x1c);

7.2 Option Value formats

• Empty:zero-length sequence of bytes.
• Opaque:an opaque sequence of bytes.
• Uint:non-negative Integer is represented in network byte.
• String:unicode string that is encoded using the UTF-8 [RFC3629] in net-unicode form.

critical/elective Option:

According to the processing of the unrecognized option is divided into critical/elective option.

-If an option is not recognized, if it is elective option, ignore it directly, if confirmable request critical option,server back to 4.02 (Bad Option).

Critical Option in--confirmable response or nonconfirmable message requires reject the message to the end.

--only applicable to non-proxying endpoints.

Unsafe or Safe-to-forward:

The handling of unrecognized option according to Proxy is divided into unsafe or safe-to-forward option.

Cache-key:

repeatable: There may be one or more of these option in a mesage.

7.3 Base Specification Options

7.3.1 Uri-host, Uri-port, Uri-path, and Uri-query

Represents an address for a resource.

• Uri-host Option Specifies the Internet Host of the resource being requested.
• Uri-port Option Specifies the Transport-layer Port number of the resource.
• Uri-path Option Specifies one segment of the absolute Path to the resource.
• Uri-query Option Specifies one argument parameterizing the resource.

7.3.2 Proxy-uri and Proxy-scheme

For Forward-proxy.

7.3.3 Content-format

Represents the type of payload in a message.

7.3.4 Accept

Indicates which content format the client can accept. If the server cannot reply to this content format, the 4.06 "not acceptable" is returned.

7.3.5 max-age

Represents the maximum time that Cached Reposne is a Fresh state, over this time, Cached response is not Fresh.

7.3.6 ETag

The server that provides the resource generates this tag, which represents the same RESOURC.

• The etag in the response.
• The etag in the request.

7.3.7 Location-path and Location-query

The Relative URI to request URL is consists either of an absolute path, a query string, or both.

7.3.8 Conditional Request Options

Causes the client to send request to the server in a specific situation. If the condition does not satisfy the client, the Request,server will return 4.12 (precondition Failed) Response code.

7.3.8.1 If-match

• Typically used in resource update (PUT), the condition is that the etag of the target resource or resource exists.
• The value of If-match option can be either an empty string or an etag.
• If you have multiple IF-MACTH option, just meet one.

7.3.8.2 None-match

• Typically used in resource update (PUT), the condition is that the target resource does not exist. If-match option does not have value.

7.3.11size1

Commonly used in block-wise transfer.

Also used when the client's package is too large, the server replies 4.13 Response Code, with SIZE1 option to tell the client the maximum value to accept.

7. chching

CoAP includes a simple caching model

Cacheability determined by response code

An option number mask determines if it is a cache key

7.1 Freshness Model

Freshness checked using the Max-age Option.

• When a response is a "Fresh" state, it can be used directly to process the request without having to visit Origin server.
• Origin Server provides a explicit expiration time (using Max-age Option) to determine the "freshness" of a response.
• The default value for Max-age option is 60s.
• If origin server does not want caching, you can set the value of Max-age option to 0.

7.2 Validation Model

Validity checked using the Etag Option.

• When a endpoint has multiple cached response, but neither "fresh", request can use ETag option, which gives origin server an opportunity to select a stored response, and update this Resposne's freshness. This process is called "validating" or "revalidating".
• Server reply 2.03 (Valid) response with ETAG option. Once received, the freshness of cached response will be updated.

So my understanding is that the ETag is a label (ENTITY-TAG) generated by the server that provides resource, and the label represents the same resource that changes over time.

8. proxying

For Safe-to-forward options must be Forward.

Forward-proxies

The function is the request sent to the server by the agent. Use Proxy-uri option in the request message to indicate the proxy, using Uri-host, Uri-port, Uri-path, and uri-query options to indicate Origin server.

Reverse-proxies

Do not use Proxy-uri Option.

COAP protocol Note [RFC7252]