idnits 2.17.1 draft-kovatsch-lwig-coap-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([I-D.ietf-core-coap]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 190: '...atagrams. These MUST be silently igno...' RFC 2119 keyword, line 192: '...reserved values, MUST be rejected with...' RFC 2119 keyword, line 356: '...serve option and MUST use a different ...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 28, 2014) is 3709 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'I-D.arkko-core-sleepy-sensors' is defined on line 918, but no explicit reference was found in the text == Outdated reference: A later version (-04) exists of draft-bormann-core-cocoa-01 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-14 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-12 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 LWIG Working Group M. Kovatsch 3 Internet-Draft ETH Zurich 4 Intended status: Informational O. Bergmann 5 Expires: September 1, 2014 Universitaet Bremen TZI 6 E. Dijk 7 Philips Research 8 X. He 9 Hitachi (China) R&D Corp. 10 C. Bormann, Ed. 11 Universitaet Bremen TZI 12 February 28, 2014 14 CoAP Implementation Guidance 15 draft-kovatsch-lwig-coap-03 17 Abstract 19 The Constrained Application Protocol (CoAP) is designed for resource- 20 constrained nodes and networks, e.g., sensor nodes in a low-power 21 lossy network (LLN). Yet to implement this Internet protocol on 22 Class 1 devices (i.e., ~ 10 KiB of RAM and ~ 100 KiB of ROM) also 23 lightweight implementation techniques are necessary. This document 24 provides lessons learned from implementing CoAP for tiny, battery- 25 operated networked embedded systems. In particular, it provides 26 guidance on correct implementation of the CoAP specification 27 [I-D.ietf-core-coap], memory optimizations, and customized protocol 28 parameters. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on September 1, 2014. 47 Copyright Notice 49 Copyright (c) 2014 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Protocol Implementation . . . . . . . . . . . . . . . . . . . 4 66 2.1. Client/Server Model . . . . . . . . . . . . . . . . . . . 4 67 2.2. Message Processing . . . . . . . . . . . . . . . . . . . 5 68 2.2.1. On-the-fly Processing . . . . . . . . . . . . . . . . 5 69 2.2.2. Internal Data Structure . . . . . . . . . . . . . . . 6 70 2.3. Duplicate Rejection . . . . . . . . . . . . . . . . . . . 6 71 2.4. Token Usage . . . . . . . . . . . . . . . . . . . . . . . 7 72 2.4.1. Tokens for Observe . . . . . . . . . . . . . . . . . 7 73 2.4.2. Tokens for Blockwise Transfers . . . . . . . . . . . 8 74 2.5. Transmission States . . . . . . . . . . . . . . . . . . . 8 75 2.5.1. Request/Response Layer . . . . . . . . . . . . . . . 9 76 2.5.2. Message Layer . . . . . . . . . . . . . . . . . . . . 10 77 2.6. Out-of-band Information . . . . . . . . . . . . . . . . . 11 78 2.7. Programming Model . . . . . . . . . . . . . . . . . . . . 11 79 2.7.1. Client . . . . . . . . . . . . . . . . . . . . . . . 12 80 2.7.2. Server . . . . . . . . . . . . . . . . . . . . . . . 12 81 3. Optimizations . . . . . . . . . . . . . . . . . . . . . . . . 13 82 3.1. Message Buffers . . . . . . . . . . . . . . . . . . . . . 13 83 3.2. Retransmissions . . . . . . . . . . . . . . . . . . . . . 14 84 3.3. Observable Resources . . . . . . . . . . . . . . . . . . 14 85 3.4. Blockwise Transfers . . . . . . . . . . . . . . . . . . . 15 86 3.5. Deduplication with Sequential MIDs . . . . . . . . . . . 15 87 4. Alternative Configurations . . . . . . . . . . . . . . . . . 18 88 4.1. Transmission Parameters . . . . . . . . . . . . . . . . . 18 89 4.2. CoAP over IPv4 . . . . . . . . . . . . . . . . . . . . . 19 90 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 91 5.1. Normative References . . . . . . . . . . . . . . . . . . 19 92 5.2. Informative References . . . . . . . . . . . . . . . . . 20 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 95 1. Introduction 97 The Constrained Application Protocol [I-D.ietf-core-coap] has been 98 designed specifically for machine-to-machine communication in 99 networks with very constrained nodes. Typical application scenarios 100 therefore include building automation, process optimization, and the 101 Internet of Things. The major design objectives have been set on 102 small protocol overhead, robustness against packet loss, and against 103 high latency induced by small bandwidth shares or slow request 104 processing in end nodes. To leverage integration of constrained 105 nodes with the world-wide Internet, the protocol design was led by 106 the REST architectural style that accounts for the scalability and 107 robustness of the Hypertext Transfer Protocol [RFC2616]. 109 Lightweight implementations benefit from this design in many 110 respects: First, the use of Uniform Resource Identifiers (URIs) for 111 naming resources and the transparent forwarding of their 112 representations in a server-stateless request/response protocol make 113 protocol translation to HTTP a straightforward task. Second, the set 114 of protocol elements that are unavoidable for the core protocol and 115 thus must be implemented on every node has been kept very small, 116 minimizing the unnecessary accumulation of "optional" features. 117 Options that - when present - are critical for message processing are 118 explicitly marked as such to force immediate rejection of messages 119 with unknown critical options. Third, the syntax of protocol data 120 units is easy to parse and is carefully defined to avoid creation of 121 state in servers where possible. 123 Although these features enable lightweight implementations of the 124 Constrained Application Protocol, there is still a tradeoff between 125 robustness and latency of constrained nodes on one hand and resource 126 demands on the other. For constrained nodes of Class 1 or even Class 127 2, the most limiting factors usually are dynamic memory needs, static 128 code size, and energy. Most implementations therefore need to 129 optimize internal buffer usage, omit idle protocol feature, and 130 maximize sleeping cycles. 132 The present document gives possible strategies to solve this tradeoff 133 for very constrained nodes (i.e., Class 1 in 134 [I-D.ietf-lwig-terminology]). For this, it provides guidance on 135 correct implementation of the CoAP specification 136 [I-D.ietf-core-coap], memory optimizations, and customized protocol 137 parameters. 139 2. Protocol Implementation 141 In the programming styles supported by very simple operating systems 142 as found on constrained nodes, preemptive multi-threading is not an 143 option. Instead, all operations are triggered by an event loop 144 system, e.g., in a send-receive-dispatch cycle. It is also common 145 practice to allocate memory statically to ensure stable behavior, as 146 no memory management unit (MMU) or other abstractions are available. 147 For a CoAP node, the two key parameters for memory usage are the 148 number of (re)transmission buffers and the maximum message size that 149 must be supported by each buffer. Often the maximum message size is 150 set far below the 1280-byte MTU of 6LoWPAN to allow more than one 151 open Confirmable transmission at a time (in particular for parallel 152 observe notifications). Note that implementations on constrained 153 platforms often not even support the full MTU. Larger messages must 154 then use blockwise transfers [I-D.ietf-core-block], while a good 155 tradeoff between 6LoWPAN fragmentation and CoAP header overhead must 156 be found. Usually the amount of available free RAM dominates this 157 decision. For Class 1 devices, the maximum message size is typically 158 128 or 256 bytes (blockwise) payload plus an estimate of the maximum 159 header size with a worst case option setting. 161 2.1. Client/Server Model 163 In general, CoAP servers can be implemented more efficiently than 164 clients. REST allows them to keep the communication stateless and 165 piggy-backed responses are not stored for retransmission, saving 166 buffer space. The use of idempotent requests also allows to relax 167 deduplication, which further decreases memory usage. It is also easy 168 to estimate the required maximum size of message buffers, since URI 169 paths, supported options, and maximum payload sizes of the 170 application are known at compile time. Hence, when the application 171 is distributed over constrained and unconstrained nodes, the 172 constrained ones should preferably have the server role. 174 HTTP-based applications have established an inversed model because of 175 the need for simple push notifications: A constrained client uses 176 POST requests to update resources on an unconstrained server whenever 177 an event, e.g., a new sensor reading, is triggered. This requirement 178 is solved by the Observe option [I-D.ietf-core-observe] of CoAP. It 179 allows servers to initiate communication and send push notifications 180 to interested client nodes. This allows a more efficient and also 181 more natural model for CoAP-based applications, where the information 182 source is in server role and can benefit from caching. 184 2.2. Message Processing 186 Apart from the required buffers, message processing is symmetric for 187 clients and servers. First the 4-byte base header has to be parsed 188 and thereby checked if it is a CoAP message. Since the encoding is 189 very dense, only a wrong Version or a datagram size smaller than four 190 bytes identify non-CoAP datagrams. These MUST be silently ignored. 191 All other message format errors, such as an incomplete datagram 192 length or the usage of reserved values, MUST be rejected with a Reset 193 (RST) message. Next the Token is read based on the TKL field. For 194 the following header options, there are two alternatives: Either 195 process the header on the fly when an option is accessed or initially 196 parse all values into an internal data structure. 198 2.2.1. On-the-fly Processing 200 The advantage of on-the-fly processing is that no additional memory 201 needs to be allocated to store the option values, which are stored 202 efficiently inline in the buffer for incoming messages. Once the 203 message is accepted for further processing, the set of options 204 contained in the received message must be decoded to check for 205 unknown critical options. To avoid multiple passes through the 206 option list, the option parser might maintain a bit-vector where each 207 bit represents an option number that is present in the received 208 request. With the wide and sparse range of option numbers, the 209 number itself cannot be used to indicate the number of left-shift 210 operations to mask the corresponding bit. Hence, an implementation- 211 specific enum of supported options should be used to mask the present 212 options of a message in the bitmap. In addition, the byte index of 213 every option (a direct pointer) can be added to a sparse list (e.g., 214 a one-dimensional array) for fast retrieval. 216 This particularly enables efficient handling of options that might 217 occur more than once such as Uri-Path. In this implementation 218 strategy, the delta is zero for any subsequent path segment, hence 219 the stored byte index for this option (e.g., 11 for Uri-Path) would 220 be overwritten to hold a pointer to only the last occurrence of that 221 option. The Uri-Path can be resolved on the fly, though, and a 222 pointer to the targeted resource stored directly in the sparse list. 223 In simpler cases, conditionals can preselect one of the repeated 224 option values. 226 Once the option list has been processed, all known critical option 227 and all elective options can be masked out in the bit-vector to 228 determine if any unknown critical option was present. If this is the 229 case, this information can be used to create a 4.02 response 230 accordingly. Note that full processing must only be done up to the 231 highest supported option number. Beyond that, only the least 232 significant bit (Critical or Elective) needs to be checked. 233 Otherwise, if all critical options are supported, the sparse list of 234 option pointers is used for further handling of the message. 236 2.2.2. Internal Data Structure 238 Using an internal data structure for all parsed options has advantage 239 when working on the option values, as they are already in a variable 240 of corresponding type, e.g., an integer in host byte order. The 241 incoming payload and byte strings of the header can be accessed 242 directly in the buffer for incoming messages using pointers (similar 243 to on-the-fly processing). This approach also benefits from a 244 bitmap. Otherwise special values must be reserved to encode an unset 245 option, which might require a larger type than required for the 246 actual value range (e.g., a 32-bit integer instead of 16-bit). 248 The byte strings (e.g., the URI) are usually not required when 249 generating the response. And since all important values were copied, 250 this alternative facilitates using the buffer for incoming messages 251 also for the assembly of outgoing messages - which can be the shared 252 IP buffer provided by the OS. 254 Setting options for outgoing messages is also easier with an internal 255 data structure. Application developers can set options independent 256 from the option number, whose order is required for the delta 257 encoding. The CoAP encoding is then applied in a serialization step 258 before sending. In contrast, assembling outgoing messages with on- 259 the-fly processing requires either extensive memmove operations to 260 insert new header options or restrictions for developers to set 261 options in their correct order. 263 2.3. Duplicate Rejection 265 If CoAP is used directly on top of UDP (i.e., in NoSec mode), it 266 needs to cope with the fact that the UDP datagram transport can 267 reorder and duplicate messages. (In contrast to UDP, DTLS has its 268 own duplicate detection.) CoAP has been designed with protocol 269 functionality such that rejection of duplicate messages is always 270 possible. It is at the discretion of the receiver if it actually 271 wants to make use of this functionality. Processing of duplicate 272 messages comes at a cost, but so does the management of the state 273 associated with duplicate rejection. The number of remote endpoints 274 that need to be managed might be vast. This can be costly in 275 particular for unconstrained nodes that have throughput in the order 276 of one hundred thousand requests per second (i.e., about 16 GiB of 277 RAM only for duplicate rejection). Deduplication is also heavy for 278 servers on Class 1 devices, as also piggy-backed responses need to be 279 stored for the case that the ACK message is lost. Hence, a receiver 280 may have good reasons to decide not to do the deduplication. 282 If duplicate rejection is indeed necessary, e.g., for non-idempotent 283 requests, it is important to control the amount of state that needs 284 to be stored. It can be reduced for instance by deduplication at 285 resource level: Knowledge of the application and supported 286 representations can minimize the amount of state that needs to be 287 kept. Duplicate rejection on the client side can be simplified by 288 choosing clever Tokens and only filter based on this information 289 (e.g., a list of Tokens currently in use or an obscured counter in 290 the Token value). 292 2.4. Token Usage 294 Tokens are chosen by the client and help to identify request/response 295 pairs that span several messages (e.g., a separate response, which 296 has a new MID). Servers do not generate Tokens and only mirror what 297 they receive from the clients. Tokens must be unique within the 298 namespace of a client throughout their lifetime. This begins when 299 being assigned to a request and ends when the open request is closed 300 by receiving and matching the final response. Neither empty ACKs nor 301 notifications (i.e., responses carrying the Observe option) terminate 302 the lifetime of a Token. 304 As already mentioned, a clever assignment of Tokens can help to 305 simplify duplicate rejection. Yet this is also important for coping 306 with client crashes. When a client restarts during an open request 307 and (unknowingly) re-uses the same Token, it might match the response 308 from the previous request to the current one. Hence, when only the 309 Token is used for matching, which is always the case for separate 310 responses, randomized Tokens with enough entropy should be used. The 311 8-byte range for Tokens even allows for one-time usage throughout the 312 lifetime of a client node. When DTLS is used, client crashes/ 313 restarts will lead to a new security handshake, thereby solving the 314 problem of mismatching responses and/or notifications. 316 2.4.1. Tokens for Observe 318 In the case of Observe [I-D.ietf-core-observe], a request will be 319 answered with multiple notifications and it can become hard to 320 determine the end of a Token lifetime. When establishing an Observe 321 relationship, the Token is registered at the server. Hence, the 322 client partially loses control of the used Token. A client can 323 attempt to cancel the relationship, which frees the Token upon 324 success (i.e., the message with code 7.31 is acknowledged; see 325 [I-D.ietf-core-observe] section 3.6). However, the client might 326 never receive the ACK due to a temporary network outages or worse, a 327 server crash. Although a network outage will also affect 328 notifications so that the Observe garbage collection could apply, the 329 server might simply not send CON notifucations during that time. 330 Alternative Observe lifetime models such as Stubbornness(tm) might 331 also keep relationships alive for longer periods. 333 Thus, Observe requests should never use the empty Token, but 334 carefully chose the value. One option is to assign and re-use 335 dedicated Tokens for each Observe relationship the client will 336 establish. This is, however, critical for spoofing attacks in NoSec 337 mode. The recommendation is to use randomized Tokens with a length 338 of at least four bytes. Thus, dedicated ranges within the 8-byte 339 Token space should be used when in NoSec mode. This also solves the 340 the problem of mismatching notifications after a client crash/ 341 restart. 343 2.4.2. Tokens for Blockwise Transfers 345 In general, blockwise transfers are independent from the Token and 346 are correlated through client endpoint address and server address and 347 resource path (destination URI). Thus, each block may be transferred 348 using a different Token. Still it can be beneficial to use the same 349 Token (it is freed upon reception of a response block) for all 350 blocks, e.g., to easily route received blocks to the same response 351 handler. 353 Special care has to be taken when Block2 is combined with Observe. 354 Notifications only carry the first block and it is up to the client 355 to retrieve the remaining ones. These GET requests do not carry the 356 Observe option and MUST use a different Token, since the Token from 357 the notification is still in use. 359 2.5. Transmission States 361 CoAP endpoints must keep transmission state to manage open requests, 362 to handle the different response modes, and to implement reliable 363 delivery at the message layer. The following finite state machines 364 (FSMs) model the transmissions of a CoAP exchange at the request/ 365 response layer and the message layer. These layers are linked 366 through actions. The M_CMD() action triggers a corresponding 367 transition at the message layer and the RR_EVT() action triggers a 368 transition at the request/response layer. The FSMs also use guard 369 conditions to distinguish between information that is only available 370 through the other layer (e.g., whether a request was sent using a CON 371 or NON message). 373 2.5.1. Request/Response Layer 375 Figure 1 depicts the two states at the request/response layer of a 376 CoAP client. When a request is issued, a "reliable_send" or 377 "unreliable_send" is triggered at the message layer. The WAITING 378 state can be left through three transitions: Either the client 379 cancels the request and triggers cancelation of a CON transmission at 380 the message layer, the client receives a failure event from the 381 message layer, or a receive event containing a response. 383 +------------CANCEL-------------------------------+ 384 | / M_CMD(cancel) | 385 | V 386 | +------+ 387 +-------+ -------RR_EVT(fail)--------------------> | | 388 |WAITING| | IDLE | 389 +-------+ -------RR_EVT(rx)[is Response]---------> | | 390 ^ / M_CMD(accept) +------+ 391 | | 392 +--------------------REQUEST----------------------+ 393 / M_CMD((un)reliable_send) 395 Figure 1: CoAP Client Request/Response Layer FSM 397 A server resource can decide at the request/response layer whether to 398 respond with a piggy-backed or a separate response. Thus, there are 399 two busy states in Figure 2, SERVING and SEPARATE. An incoming 400 receive event with a NON request directly triggers the transition to 401 the SEPARATE state. 403 +--------+ <----------RR_EVT(rx)[is NON]---------- +------+ 404 |SEPARATE| | | 405 +--------+ ----------------RESPONSE--------------> | IDLE | 406 ^ / M_CMD((un)reliable_send) | | 407 | +---> +------+ 408 |EMPTY_ACK | | 409 |/M_CMD(accept) | | 410 | | | 411 | | | 412 +--------+ | | 413 |SERVING | --------------RESPONSE------------+ | 414 +--------+ / M_CMD(accept) | 415 ^ | 416 +------------------------RR_EVT(rx)[is CON]--------+ 418 Figure 2: CoAP Server Request/Response Layer FSM 420 2.5.2. Message Layer 422 Figure 3 shows the different states of a CoAP endpoint per message 423 exchange. Besides the linking action RR_EVT(), the message layer has 424 a TX action to send a message. For sending and receiving NONs, the 425 endpoint remains in its CLOSED state. When sending a CON, the 426 endpoint remains in RELIABLE_TX and keeps retransmitting until the 427 transmission times out, it receives a matching RST, the request/ 428 response layer cancels the transmission, or the endpoint receives an 429 implicit acknowledgement through a matching NON or CON. Whenever the 430 endpoint receives a CON, it transitions into the ACK_PENDING state, 431 which can be left by sending the corresponding ACK. 433 +-----------+ <-------M_CMD(reliable_send)-----+ 434 | | / TX(con) \ 435 | | +--------------+ 436 | | ---TIMEOUT(RETX_WINDOW)------> | | 437 |RELIABLE_TX| / RR_EVT(fail) | | 438 | | ---------------------RX_RST--> | | <----+ 439 | | / RR_EVT(fail) | | | 440 +-----------+ ----M_CMD(cancel)------------> | CLOSED | | 441 ^ | | \ \ | | --+ | 442 | | | \ +-------------------RX_ACK---> | | | | 443 +*1+ | \ / RR_EVT(rx) | | | | 444 | +----RX_NON-------------------> +--------------+ | | 445 | / RR_EVT(rx) ^ ^ ^ ^ | | | | | | 446 | | | | | | | | | | | 447 | | | | +*2+ | | | | | 448 | | | +--*3--+ | | | | 449 | | +----*4----+ | | | 450 | +------*5------+ | | 451 | +---------------+ | | 452 | | ACK_PENDING | <--RX_CON-------------+ | 453 +----RX_CON----> | | / RR_EVT(rx) | 454 / RR_EVT(rx) +---------------+ ---------M_CMD(accept)---+ 455 / TX(ack) 457 *1: TIMEOUT(RETX_TIMEOUT) / TX(con) 458 *2: M_CMD(unreliable_send) / TX(non) 459 *3: RX_NON / RR_EVT(rx) 460 *4: RX_RST / REMOVE_OBSERVER 461 *5: RX_ACK 463 Figure 3: CoAP Message Layer FSM 465 T.B.D.: (i) Rejecting messages (can be triggered at message and 466 request/response layer). (ii) ACKs can also be triggered at both 467 layers. 469 2.6. Out-of-band Information 471 They CoAP implementation can also leverage out-of-band information, 472 that might also trigger some of the transitions shown in Section 2.5. 473 In particular ICMP messages can inform about unreachable remote 474 endpoints or whole network outages. This information can be used to 475 pause or cancel ongoing transmission to conserve energy. Providing 476 ICMP information to the CoAP implementation is easier in constrained 477 environments, where developers usually can adapt the underlying OS 478 (or firmware). This is not the case on general purpose platforms 479 that have full-fledged OSes and make use of high-level programming 480 frameworks. 482 The most important ICMP messages are host, network, port, or protocol 483 unreachable errors. They should cause the cancelation of ongoing CON 484 transmissions and clearing of Observe relationships. Requests to 485 this destination should be paused for a sensable interval. In 486 addition, the device could indicate of this error through a 487 notification to a management endpoint or external status indicator, 488 since the cause could be a misconfiguration or general unavailability 489 of the required service. Problems reported through the Parameter 490 Problem message are usually caused through a similar fundamental 491 problem. 493 The CoAP specification recommends to ignore Source Quench and Time 494 Exceeded ICMP messages, though. Source Quench messages inform the 495 sender to reduce the rate of packets. However, this mechanism is 496 deprecated through [RFC6633]. CoAP also comes with its own 497 congestion control mechanism, which is already designed 498 conservatively. If an advanced mechanism is required to better 499 utilize the network, [I-D.bormann-core-cocoa] should be implemented. 500 Time Exceeded messages inform about possible routing loops or a too 501 small initial Hop Limit value. This is out of scope for CoAP 502 implementations, though. 504 2.7. Programming Model 506 The event-driven approach, which is common in event-loop-based 507 firmware, has also proven very efficient for embedded operating 508 systems [TinyOS], [Contiki]. Note that an OS is not necessarily 509 required and a traditional firmware approach can suffice for Class 1 510 devices. Event-driven systems use split-phase operations (i.e., 511 there are no blocking functions, but functions return and an event 512 handler is called once a long-lasting operation completes) to enable 513 cooperative multi-threading with a single stack. 515 Bringing a Web transfer protocol to constrained environments does not 516 only change the networking of the corresponding systems, but also the 517 programming model. The complexity of event-driven systems can be 518 hidden through APIs that resemble classic RESTful Web service 519 implementations. 521 2.7.1. Client 523 An API for asynchronous requests with response handler functions goes 524 hand-in-hand with the event-driven approach. Synchronous requests 525 with a blocking send function can facilitate applications that 526 require strictly ordered, sequential request execution (e.g., to 527 control a physical process) or other checkpointing (e.g., starting 528 operation only after registration with the resource directory was 529 successful). However, this can also be solved by triggering the next 530 operation in the response handlers. Furthermore, as mentioned in 531 Section 2.1, it is more like that complex control flow is done by 532 more powerful devices and Class 1 devices predominantly run a CoAP 533 server (which might have a minimalistic client to communicate with a 534 resource directory). 536 2.7.2. Server 538 On CoAP servers, the event-driven nature can be hidden through 539 resource handler abstractions as known from traditional REST 540 frameworks. The following types of RESTful resources have proven 541 useful to provide an intuitive API on constrained event-driven 542 systems: 544 NORMAL A normal resource defined by a static Uri-Path and an 545 associated resource handler function. Allowed methods could 546 already be filtered by the implementation based on flags. This is 547 the basis for all other resource types. 549 PARENT A parent resource manages several sub-resources under a given 550 base path by programmatically evaluating the Uri-Path. Defining a 551 URI template (see [RFC6570]) would be a convenient way to pre- 552 parse arguments given in the Uri-Path. 554 PERIODIC A resource that has an additional handler function that is 555 triggered periodically by the CoAP implementation with a resource- 556 specific interval. It can be used to sample a sensor or perform 557 similar periodic updates of its state. Usually, a periodic 558 resource is observable and sends the notifications by triggering 559 its normal resource handler from the periodic handler. These 560 periodic tasks are quite common for sensor nodes, thus it makes 561 sense to provide this functionality in the CoAP implementation and 562 avoid redundant code in every resource. 564 EVENT An event resource is similar to an periodic resource, only 565 that the second handler is called by an irregular event such as a 566 button. 568 SEPARATE Separate responses are usually used when handling a request 569 takes more time, e.g., due to a slow sensor or UART-based 570 subsystems. To not fully block the system during this time, the 571 handler should also employ split-phase execution: The resource 572 handler returns as soon as possible and an event handler resumes 573 responding when the result is ready. The separate resource type 574 can abstract from the split-phase operation and take care of 575 temporarily storing the request information that is required later 576 in the result handler to send the response (e.g., source address 577 and Token). 579 3. Optimizations 581 3.1. Message Buffers 583 The cooperative multi-threading of an event loop system allows to 584 optimize memory usage through in-place processing and reuse of 585 buffers, in particular the IP buffer provided by the OS or firmware. 587 CoAP servers can significantly benefit from in-place processing, as 588 they can create responses directly in the incoming IP buffer. Note 589 that an embedded OS usually only has a single buffer for incoming and 590 outgoing IP packets. The first few bytes of the basic header are 591 usually parsed into an internal data structure and can be overwritten 592 without harm. Thus, empty ACKs and RST messages can promptly be 593 assembled and sent using the IP buffer. Also when a CoAP server only 594 sends piggy-backed or Non-confirmable responses, no additional buffer 595 is required at the application layer. This, however, requires 596 careful timing so that no incoming data is overwritten before it was 597 processed. Because of cooperative multi-threading, this requirement 598 is relaxed, though. Once the message is sent, the IP buffer can 599 accept new messages again. This does not work for Confirmable 600 messages, however. They need to be stored for retransmission and 601 would block any further IP communication. 603 Depending on the number of requests that can be handled in parallel, 604 an implementation might create a stub response filled with any option 605 that has to be copied from the original request to the separate 606 response, especially the Token option. The drawback of this 607 technique is that the server must be prepared to receive 608 retransmissions of the previous (Confirmable) request to which a new 609 acknowledgement must be generated. If memory is an issue, a single 610 buffer can be used for both tasks: Only the message type and code 611 must be updated, changing the message id is optional. Once the 612 resource representation is known, it is added as new payload at the 613 end of the stub response. Acknowledgements still can be sent as 614 described before as long as no additional options are required to 615 describe the payload. 617 3.2. Retransmissions 619 CoAP's reliable transmissions require the before-mentioned 620 retransmission buffers. Messages, such as the requests of a client, 621 should be stored in serialized form. For servers, retransmissions 622 apply for Confirmable separate responses and Confirmable 623 notifications [I-D.ietf-core-observe]. As separate responses stem 624 from long-lasting resource handlers, the response should be stored 625 for retransmission instead of re-dispatching a stored request (which 626 would allow for updating the representation). For Confirmable 627 notifications, please see Section 2.6, as simply storing the response 628 can break the concept of eventual consistency. 630 String payloads such as JSON require a buffer to print to. By 631 splitting the retransmission buffer into header and payload part, it 632 can be reused. First to generate the payload and then storing the 633 CoAP message by serializing into the same memory. Thus, providing a 634 retransmission for any message type can save the need for a separate 635 application buffer. This, however, requires an estimation about the 636 maximum expected header size to split the buffer and a memmove to 637 concatenate the two parts. 639 For platforms that disable clock tick interrupts in sleep states, the 640 application must take into consideration the clock deviation that 641 occurs during sleep (or ensure to remain in idle state until the 642 message has been acknowledged or the maximum number of 643 retransmissions is reached). Since CoAP allows up to four 644 retransmissions with a binary exponential back-off it could take up 645 to 45 seconds until the send operation is complete. Even in idle 646 state, this means substantial energy consumption for low-power nodes. 647 Implementers therefore might choose a two-step strategy: First, do 648 one or two retransmissions and then, in the later phases of back-off, 649 go to sleep until the next retransmission is due. In the meantime, 650 the node could check for new messages including the acknowledgement 651 for any Confirmable message to send. 653 3.3. Observable Resources 655 For each observer, the server needs to store at least address, port, 656 token, and the last outgoing message ID. The latter is needed to 657 match incoming RST messages and cancel the observe relationship. 659 It is favorable to have one retransmission buffer per observable 660 resource that is shared among all observers. Each notification is 661 serialized once into this buffer and only address, port, and token 662 are changed when iterating over the observer list (note that 663 different token lengths might require realignment). The advantage 664 becomes clear for Confirmable notifications: Instead of one 665 retransmission buffer per observer, only one buffer and only 666 individual retransmission counters and timers in the list entry need 667 to be stored. When the notifications can be sent fast enough, even a 668 single timer would suffice. Furthermore, per-resource buffers 669 simplify the update with a new resource state during open deliveries. 671 3.4. Blockwise Transfers 673 Blockwise transfers have the main purpose of providing fragmentation 674 at the application layer, where partial information can be processed. 675 This is not possible at lower layers such as 6LoWPAN, as only 676 assembled packets can be passed up the stack. While 677 [I-D.ietf-core-block] also anticipates atomic handling of blocks, 678 i.e., only fully received CoAP messages, this is not possible on 679 Class 1 devices. 681 When receiving a blockwise transfer, each blocks is usually passed to 682 a handler function that for instance performs stream processing or 683 writes the blocks to external memory such as flash. Although there 684 are no restrictions in [I-D.ietf-core-block], it is beneficial for 685 Class 1 devices to only allow ordered transmission of blocks. 686 Otherwise on-the-fly processing would not be possible. 688 When sending a blockwise transfer, Class 1 devices usually do not 689 have sufficient memory to print the full message into a buffer, and 690 slice and send it in a second step. When transferring the CoRE Link 691 Format from /.well-known/core for instance, a generator function is 692 required that generates slices of a large string with a specific 693 offset length (a 'sonprintf()'). This functionality is required 694 recurrently and should be included in a library. 696 3.5. Deduplication with Sequential MIDs 698 CoAP's duplicate rejection functionality can be straightforwardly 699 implemented in a CoAP endpoint by storing, for each remote CoAP 700 endpoint ("peer") that it communicates with, a list of recently 701 received CoAP Message IDs (MIDs) along with some timing information. 702 A CoAP message from a peer with a MID that is in the list for that 703 peer can simply be discarded. 705 The timing information in the list can then be used to time out 706 entries that are older than the _expected extent of the re-ordering_, 707 an upper bound for which can be estimated by adding the _potential 708 retransmission window_ ([I-D.ietf-core-coap] section "Reliable 709 Messages") and the time packets can stay alive in the network. 711 Such a straightforward implementation is suitable in case other CoAP 712 endpoints generate random MIDs. However, this storage method may 713 consume substantial RAM in specific cases, such as: 715 o many clients are making periodic, non-idempotent requests to a 716 single CoAP server; 718 o one client makes periodic requests to a large number of CoAP 719 servers and/or requests a large number of resources; where servers 720 happen to mostly generate separate CoAP responses (not piggy- 721 backed); 723 For example, consider the first case where the expected extent of re- 724 ordering is 50 seconds, and N clients are sending periodic POST 725 requests to a single CoAP server during a period of high system 726 activity, each on average sending one client request per second. The 727 server would need 100 * N bytes of RAM to store the MIDs only. This 728 amount of RAM may be significant on a RAM-constrained platform. On a 729 number of platforms, it may be easier to allocate some extra program 730 memory (e.g. Flash or ROM) to the CoAP protocol handler process than 731 to allocate extra RAM. Therefore, one may try to reduce RAM usage of 732 a CoAP implementation at the cost of some additional program memory 733 usage and implementation complexity. 735 Some CoAP clients generate MID values by a using a Message ID 736 variable [I-D.ietf-core-coap] that is incremented by one each time a 737 new MID needs to be generated. (After the maximum value 65535 it 738 wraps back to 0.) We call this behavior "sequential" MIDs. One 739 approach to reduce RAM use exploits the redundancy in sequential MIDs 740 for a more efficient MID storage in CoAP servers. 742 Naturally such an approach requires, in order to actually reduce RAM 743 usage in an implementation, that a large part of the peers follow the 744 sequential MID behavior. To realize this optimization, the authors 745 therefore RECOMMEND that CoAP endpoint implementers employ the 746 "sequential MID" scheme if there are no reasons to prefer another 747 scheme, such as randomly generated MID values. 749 Security considerations might call for a choice for 750 (pseudo)randomized MIDs. Note however that with truly randomly 751 generated MIDs the probability of MID collision is rather high in use 752 cases as mentioned before, following from the Birthday Paradox. For 753 example, in a sequence of 52 randomly drawn 16-bit values the 754 probability of finding at least two identical values is about 2 755 percent. 757 From here on we consider efficient storage implementations for MIDs 758 in CoAP endpoints, that are optimized to store "sequential" MIDs. 759 Because CoAP messages may be lost or arrive out-of-order, a solution 760 has to take into account that received MIDs of CoAP messages are not 761 actually arriving in a sequential fashion, due to lost or reordered 762 messages. Also a peer might reset and lose its MID counter(s) state. 763 In addition, a peer may have a single Message ID variable used in 764 messages to many CoAP endpoints it communicates with, which partly 765 breaks sequentiality from the receiving CoAP endpoint's perspective. 766 Finally, some peers might use a randomly generated MID values 767 approach. Due to these specific conditions, existing sliding window 768 bitfield implementations for storing received sequence numbers are 769 typically not directly suitable for efficiently storing MIDs. 771 Table 1 shows one example for a per-peer MID storage design: a table 772 with a bitfield of a defined length _K_ per entry to store received 773 MIDs (one per bit) that have a value in the range [MID_i + 1 , MID_i 774 + K]. 776 +----------+----------------+-----------------+ 777 | MID base | K-bit bitfield | base time value | 778 +----------+----------------+-----------------+ 779 | MID_0 | 010010101001 | t_0 | 780 | | | | 781 | MID_1 | 111101110111 | t_1 | 782 | | | | 783 | ... etc. | | | 784 +----------+----------------+-----------------+ 786 Table 1: A per-peer table for storing MIDs based on MID_i 788 The presence of a table row with base MID_i (regardless of the 789 bitfield values) indicates that a value MID_i has been received at a 790 time t_i. Subsequently, each bitfield bit k (0...K-1) in a row i 791 corresponds to a received MID value of MID_i + k + 1. If a bit k is 792 0, it means a message with corresponding MID has not yet been 793 received. A bit 1 indicates such a message has been received already 794 at approximately time t_i. This storage structure allows e.g. with 795 k=64 to store in best case up to 130 MID values using 20 bytes, as 796 opposed to 260 bytes that would be needed for a non-sequential 797 storage scheme. 799 The time values t_i are used for removing rows from the table after a 800 preset timeout period, to keep the MID store small in size and enable 801 these MIDs to be safely re-used in future communications. (Note that 802 the table only stores one time value per row, which therefore needs 803 to be updated on receipt of another MID that is stored as a single 804 bit in this row. As a consequence of only storing one time value per 805 row, older MID entries typically time out later than with a simple 806 per-MID time value storage scheme. The endpoint therefore needs to 807 ensure that this additional delay before MID entries are removed from 808 the table is much smaller than the time period after which a peer 809 starts to re-use MID values due to wrap-around of a peer's MID 810 variable. One solution is to check that a value t_i in a table row 811 is still recent enough, before using the row and updating the value 812 t_i to current time. If not recent enough, e.g. older than N 813 seconds, a new row with an empty bitfield is created.) [Clearly, 814 these optimizations would benefit if the peer were much more 815 conservative about re-using MIDs than currently required in the 816 protocol specification.] 818 The optimization described is less efficient for storing randomized 819 MIDs that a CoAP endpoint may encounter from certain peers. To solve 820 this, a storage algorithm may start in a simple MID storage mode, 821 first assuming that the peer produces non-sequential MIDs. While 822 storing MIDs, a heuristic is then applied based on monitoring some 823 "hit rate", for example, the number of MIDs received that have a Most 824 Significant Byte equal to that of the previous MID divided by the 825 total number of MIDs received. If the hit rate tends towards 1 over 826 a period of time, the MID store may decide that this particular CoAP 827 endpoint uses sequential MIDs and in response improve efficiency by 828 switching its mode to the bitfield based storage. 830 4. Alternative Configurations 832 4.1. Transmission Parameters 834 When a constrained network of CoAP nodes is not communicating over 835 the Internet, for instance because it is shielded by a proxy or a 836 closed deployment, alternative transmission parameters can be used. 837 Consequently, the derived time values provided in 838 [I-D.ietf-core-coap] section 4.8.2 will also need to be adjusted, 839 since most implementations will encode their absolute values. 841 Static adjustments require a fixed deployment with a constant number 842 or upper bound for the number of nodes, number of hops, and expected 843 concurrent transmissions. Furthermore, the stability of the wireless 844 links should be evaluated. ACK_TIMEOUT should be chosen above the 845 xx% percentile of the round-trip time distribution. 846 ACK_RANDOM_FACTOR depends on the number of nodes on the network. 847 MAX_RETRANSMIT should be chosen suitable for the targeted 848 application. A lower bound for LEISURE can be calculated as 849 lb_Leisure = S * G / R 851 where S is the estimated response size, G the group size, and R the 852 target data transfer rate (see [I-D.ietf-core-coap] section 8.2). 853 NSTART and PROBING_RATE depend on estimated network utilization. If 854 the main cause for loss are weak links, higher values can be chosen. 856 Dynamic adjustments will be performed by advanced congestion control 857 mechanisms such as [I-D.bormann-core-cocoa]. They are required if 858 the main cause for message loss is network or endpoint congestion. 859 Semi-dynamic adjustments could be implemented by disseminating new 860 static transmission parameters to all nodes when the network 861 configuration changes (e.g., new nodes are added or long-lasting 862 interference is detected). 864 4.2. CoAP over IPv4 866 CoAP was designed for the properties of IPv6, which dominating in 867 constrained environments because of the 6LowPAN adaption layer 868 [RFC6282]. In particular, the size limitations of CoAP are tailored 869 to the minimal MTU of 1280 bytes. Until the transition towards IPv6 870 converges, CoAP nodes might also communicate overIPv4, though. 871 Sections 4.2 and 4.6 of the base specification [I-D.ietf-core-coap] 872 already provide guidance and implementation notes to handle the 873 smaller minimal MTUs of IPv4. 875 5. References 877 5.1. Normative References 879 [I-D.bormann-core-cocoa] 880 Bormann, C., "CoAP Simple Congestion Control/Advanced", 881 draft-bormann-core-cocoa-01 (work in progress), February 882 2014. 884 [I-D.ietf-core-block] 885 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 886 draft-ietf-core-block-14 (work in progress), October 2013. 888 [I-D.ietf-core-coap] 889 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 890 Application Protocol (CoAP)", draft-ietf-core-coap-18 891 (work in progress), June 2013. 893 [I-D.ietf-core-observe] 894 Hartke, K., "Observing Resources in CoAP", draft-ietf- 895 core-observe-12 (work in progress), February 2014. 897 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 898 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 899 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 901 [RFC6282] Hui, J. and P. Thubert, "Compression Format for IPv6 902 Datagrams over IEEE 802.15.4-Based Networks", RFC 6282, 903 September 2011. 905 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 906 and D. Orchard, "URI Template", RFC 6570, March 2012. 908 [RFC6633] Gont, F., "Deprecation of ICMP Source Quench Messages", 909 RFC 6633, May 2012. 911 5.2. Informative References 913 [Contiki] Dunkels, A., Groenvall, B., and T. Voigt, "Contiki - a 914 Lightweight and Flexible Operating System for Tiny 915 Networked Sensors", Proceedings of the First IEEE Workshop 916 on Embedded Networked Sensors , November 2004. 918 [I-D.arkko-core-sleepy-sensors] 919 Arkko, J., Rissanen, H., Loreto, S., Turanyi, Z., and O. 920 Novo, "Implementing Tiny COAP Sensors", draft-arkko-core- 921 sleepy-sensors-01 (work in progress), July 2011. 923 [I-D.ietf-lwig-terminology] 924 Bormann, C., Ersue, M., and A. Keranen, "Terminology for 925 Constrained Node Networks", draft-ietf-lwig-terminology-07 926 (work in progress), February 2014. 928 [TinyOS] Levis, P., Madden, S., Polastre, J., Szewczyk, R., 929 Whitehouse, K., Woo, A., Gay, D., Woo, A., Hill, J., 930 Welsh, M., Brewer, E., and D. Culler, "TinyOS: An 931 Operating System for Sensor Networks", Ambient 932 intelligence, Springer (Berlin Heidelberg), ISBN 933 978-3-540-27139-0 , 2005. 935 Authors' Addresses 937 Matthias Kovatsch 938 ETH Zurich 939 Universitaetstrasse 6 940 CH-8092 Zurich 941 Switzerland 943 Email: kovatsch@inf.ethz.ch 944 Olaf Bergmann 945 Universitaet Bremen TZI 946 Postfach 330440 947 D-28359 Bremen 948 Germany 950 Email: bergmann@tzi.org 952 Esko Dijk 953 Philips Research 955 Email: esko.dijk@philips.com 957 Xuan He 958 Hitachi (China) R&D Corp. 959 301, Tower C North, Raycom, 2 Kexuyuan Nanlu 960 Beijing, 100190 961 P.R.China 963 Email: xhe@hitachi.cn 965 Carsten Bormann (editor) 966 Universitaet Bremen TZI 967 Postfach 330440 968 D-28359 Bremen 969 Germany 971 Phone: +49-421-218-63921 972 Email: cabo@tzi.org