1. What is CoAP
“The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained networks in the Internet of Things. The protocol is designed for machine-to-machine (M2M) applications such as smart energy and building automation.”
2. Features
- 基於REST架構：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 multicast support.
- 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 are carried in CoAP messages, which include either a Method Code or Response Code.
Request的Method code有GET, POST, PUT, DELETE四種。
Response有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 (01 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).一般寫成c.dd的形式，可以參考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: 在CoAP mesage中可以攜帶一些列的options (以Option Number表示)。每一個option組成如下:
Option Delta：4-bit unsigned integer. A value between 0 and 12.
如果Option Delta == 13， 那么Option Delta (extended)部分為1 byte，Option Delta = 13+Option Delta (extended)
如果Option Delta == 14， 那么Option Delta (extended)部分為2 byte，Option Delta = 14+255+Option Delta (extended)
Option Delta == 15無效。
Option Length：4-bit unsigned integer. A value between 0 and 12.
如果Option Length== 13， 那么Option Length(extended)部分為1 byte，Option Length= 13+Option Length(extended)
如果Option Length== 14， 那么Option Length(extended)部分為2 byte，Option Length= 14+255+Option Length(extended)
Option Delta == 15無效。
Option Number的計算：
Option Number從option delta中得到。The Option Number is calculated by simply summing the Option Delta values of this and all previous options before it.也就是說某一個option的option number就是它之前所有Option的Option delta和它自己的option delta加起來的值。
5. Message Transmission
有四種消息類型： Confirmable (0), Non-confirmable (1), Acknowledgement (2), or Reset (3).
5.1 Messages Transmitted Reliably
- 使用Confirmable (CON) message，Request和Response都可以使用這種Type.
- 收到Confirmable (CON) message后有兩種選擇，(a)回Acknowledgement message (b)Reject the message.
- 如果要拒絕Confirmable (CON) message，則發送Reset (RST) message，然后忽略這個消息。
- 重傳。UDP不可靠，Sender發出Confirmable (CON) message后依靠a timeout and a retransmission counter來確定重傳時機。
5.2 Messages Transmitted without Reliability
- Request和Response都可以使用這種Type.
- 不需要對方回Acknowledgement.
- 果要拒絕Non-confirmable (NON) message，則發送Reset (RST) message，然后忽略這個消息。
總結下Mesage Type的使用如下：
*表示不是正常的操作，只是為了引起對方回Reset message(CoAP ping)。
6. Request/Response
6.1 Requset
- CoAP supports the basic methods of GET, POST, PUT, and DELETE.
6.1.1 Method Code
- GET:獲取Server上的資源。Server可能回2.05 (Content) or 2.03 (Valid) Response Code。
- POST:通常用來創建新的資源或者更新資源。如果資源已經被創建，Server回2.01 (Created) Response Code；如果PSOT成功但是Server沒有創建資源，Server回2.04 (Changed) Response Code；如果POST成功導致目標資源刪除，Server回2.02 (Deleted) Response Code。
- PUT:更新Server上的資源。如果資源存在，回2.04(Changed) Response Code；如果資源不存在，則Server可能會創建資源，回2.01 (Created) Response Code。如果資源不能被創建或修改，則回Error Response.
- DELETE：刪除Server上的資源。回2.02 (Deleted) Response Code。
6.2 Response
有Piggybacked Response, Separate Response, Non-confirmable Response三種類型。
- Piggybacked Response. 最常用的類型，Reponse內容直接放在acknowledges中。
- Separate Response. Server暫時沒辦法直接回(可能需要更多的時間准備)，直接回Empty Acknowledgement。當Server准備好了，給Client發Confirmable message(也可以是Non-confirmable message)，最后Client回Acknowledgement。如果Server在回復Clinet之前又收到Client的重傳，那么也回Empty Acknowledgement。
- Non-confirmable Response. Client發出Non-confirmable message，Server一般也回Non-confirmable message。Spec說Server也可以發Confirmable message[P14].
三個Response類型的例子：
可以看到Server回Separate Response的時候，Token和Client的Request時的Token是一致的，但是Message ID已經變掉了。
6.2.1 Response Code
- Success:2.xx
- Client Error:4.xx
- Server Error:5.xx
Success 2.xx
- 2.01 Created. 回復POST或者PUT。
- 2.02 Deleted.回復DELETE，有些情況下的POST。
- 2.03 Valid.Indicate that the response identified by the entity-tag identified by the included ETag Option is valid.所以，Response必須帶ETag Option。
- 2.04 Changed.回復POST和PUT。
- 2.05 Content.回復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
不同的Option有不同Option Number來表示。
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 that is represented in network byte.
- string:Unicode string that is encoded using UTF-8 [RFC3629] in Net-Unicode form.
Critical/Elective Option：
根據對於未識別的Option的處理分為Critical/Elective Option。
--如果某個Option未被識別，如果是Elective Option，直接忽略；如果是Confirmable request中的Critical Option，Server回4.02 (Bad Option)。
--Confirmable response或者Nonconfirmable message中的Critical Option，對端需要Reject the message。
--只適用於non-proxying endpoints。
Unsafe or Safe-to-Forward：
根據Proxy對於未被識別的Option的處理分為Unsafe or Safe-to-Forward Option。
Cache-Key：
Repeatable：在一個mesage中可能有一個或者多個這樣的option。
7.3 Base specification Options
7.3.1 Uri-Host, Uri-Port, Uri-Path, and Uri-Query
表示一個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
用於forward-proxy。
7.3.3 Content-Format
表示Message中Payload的類型。
7.3.4 Accept
表明Client可以接受哪種content format。如果Server不能回復此種content format，則回4.06 "Not Acceptable"。
7.3.5 Max-Age
表示Cached reposne 為Fresh狀態的最大時間，超過這個時間，Cached Response為Not Fresh。
7.3.6 ETag
- 和HTTP協議中的ETag功能類似。提供Resource的Server產生這個Tag，ETag是一個可以與Web資源關聯的記號。
- 當Client GET時，server傳回Etag給client。那么下次client去訪問server的同一個Resource時就可以帶上這個ETag來知道server端的資源有沒有改變。
- 經常和If-Match/If-None-Match配合來使用。
一個HTTP協議使用ETag的例子：
客戶端請求一個頁面（A）。 服務器返回頁面A，並在給A加上一個ETag。 客戶端展現該頁面，並將頁面連同ETag一起緩存。 客戶再次請求頁面A，並將上次請求時服務器返回的ETag一起傳遞給服務器。 服務器檢查該ETag，並判斷出該頁面自上次客戶端請求之后還未被修改，直接返回響應304（未修改——Not Modified）和一個空的響應體。
7.3.7 Location-Path and Location-Query
Relative URI to request URL that consists either of an absolute path, a query string, or both.
7.3.8 Conditional Request Options
使Client在某種特定情況下才向Server發Request。如果條件不滿足Client發了request，Server會回4.12 (Precondition Failed) Response code。
7.3.8.1 if-Match
- 通常用在resource update(PUT)，條件是目標Resource或者Resource的Etag存在。
- If-Match Option的Value可以是empty string或者一個ETag。
- 有多個If-Macth Option的話，只要滿足一個即可。
7.3.8.2 None-Match
- 通常用在resource update(PUT)，條件是目標Resource不存在。If-Match Option沒有Value。
7.3.11Size1
常用在Block-wise Transfer中。
也用在當Client的包太大時，Server回復4.13 Response code，帶上Size1 Option告訴Client能接受的最大值。
8. Caching
CoAP includes a simple caching model
Cacheability determined by response code.
An option number mask determines if it is a cache key.
8.1 Freshness model
Freshness checked using the Max-Age Option。
- 當一個response是“Fresh”狀態時，它可以直接用來處理Request，而不用去訪問origin server。
- Origin server提供一個explicit expiration time（利用Max-Age Option）來決定某個response的“freshness”。
- Max-Age option默認值是60s。
- 如果Origin server不希望caching，可以設置Max-Age option的value為0。
8.2 Validation model
Validity checked using the Etag Option。
- 當一個endpoint有多個cached response，但都不“fresh”時，Request可以使用ETag Option，作用是給origin server一個機會來選擇一個stored response，並且update這個resposne的freshness。這個過程叫做“validating"”或者“revalidating”。
- Server回復2.03 (Valid) response with Etag option。收到后就就會更新cached response的freshness。
所以我的理解是ETag就是一個標簽(entity-tag)，由提供Resource的Server生成，標簽表示的是隨時間變化的同一個Resource。
9. Proxying
對於Safe-to-Forward options必須forward。
Forward-Proxies
作用是代理發往Server的Request。在Request message中使用Proxy-Uri Option表明Proxy，使用Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options表明origin server。
Reverse-Proxies
不使用Proxy-Uri Option。