idnits 2.17.1 draft-ietf-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 06, 2015) is 3216 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: '0x1234' is mentioned on line 335, but not defined == Missing Reference: '0x4711' is mentioned on line 349, but not defined == Missing Reference: '0x7a10' is mentioned on line 396, but not defined == Missing Reference: '0x23bb' is mentioned on line 414, but not defined == Missing Reference: '0x7a11' is mentioned on line 409, but not defined == Outdated reference: A later version (-04) exists of draft-bormann-core-cocoa-02 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-17 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) == Outdated reference: A later version (-06) exists of draft-becker-core-coap-sms-gprs-05 == Outdated reference: A later version (-07) exists of draft-savolainen-core-coap-websockets-04 == Outdated reference: A later version (-11) exists of draft-silverajan-core-coap-alternative-transports-08 == Outdated reference: A later version (-05) exists of draft-tschofenig-core-coap-tcp-tls-04 Summary: 1 error (**), 0 flaws (~~), 12 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: January 7, 2016 C. Bormann, Ed. 6 Universitaet Bremen TZI 7 July 06, 2015 9 CoAP Implementation Guidance 10 draft-ietf-lwig-coap-03 12 Abstract 14 The Constrained Application Protocol (CoAP) is designed for resource- 15 constrained nodes and networks such as sensor nodes in a low-power 16 lossy network (LLN). Yet to implement this Internet protocol on 17 Class 1 devices (as per RFC 7228, ~ 10 KiB of RAM and ~ 100 KiB of 18 ROM) also lightweight implementation techniques are necessary. This 19 document provides lessons learned from implementing CoAP for tiny, 20 battery-operated networked embedded systems. In particular, it 21 provides guidance on correct implementation of the CoAP specification 22 RFC 7252, memory optimizations, and customized protocol parameters. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on January 7, 2016. 41 Copyright Notice 43 Copyright (c) 2015 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Protocol Implementation . . . . . . . . . . . . . . . . . . . 4 60 2.1. Client/Server Model . . . . . . . . . . . . . . . . . . . 4 61 2.2. Message Processing . . . . . . . . . . . . . . . . . . . 5 62 2.2.1. On-the-fly Processing . . . . . . . . . . . . . . . . 5 63 2.2.2. Internal Data Structure . . . . . . . . . . . . . . . 6 64 2.3. Message ID Usage . . . . . . . . . . . . . . . . . . . . 6 65 2.3.1. Duplicate Rejection . . . . . . . . . . . . . . . . . 7 66 2.3.2. MID Namespaces . . . . . . . . . . . . . . . . . . . 7 67 2.3.3. Relaxation on the Server . . . . . . . . . . . . . . 8 68 2.3.4. Relaxation on the Client . . . . . . . . . . . . . . 9 69 2.4. Token Usage . . . . . . . . . . . . . . . . . . . . . . . 9 70 2.4.1. Tokens for Observe . . . . . . . . . . . . . . . . . 10 71 2.4.2. Tokens for Blockwise Transfers . . . . . . . . . . . 11 72 2.5. Transmission States . . . . . . . . . . . . . . . . . . . 11 73 2.5.1. Request/Response Layer . . . . . . . . . . . . . . . 12 74 2.5.2. Message Layer . . . . . . . . . . . . . . . . . . . . 13 75 2.6. Out-of-band Information . . . . . . . . . . . . . . . . . 14 76 2.7. Programming Model . . . . . . . . . . . . . . . . . . . . 15 77 2.7.1. Client . . . . . . . . . . . . . . . . . . . . . . . 15 78 2.7.2. Server . . . . . . . . . . . . . . . . . . . . . . . 16 79 3. Optimizations . . . . . . . . . . . . . . . . . . . . . . . . 17 80 3.1. Message Buffers . . . . . . . . . . . . . . . . . . . . . 17 81 3.2. Retransmissions . . . . . . . . . . . . . . . . . . . . . 17 82 3.3. Observable Resources . . . . . . . . . . . . . . . . . . 18 83 3.4. Blockwise Transfers . . . . . . . . . . . . . . . . . . . 19 84 3.5. Deduplication with Sequential MIDs . . . . . . . . . . . 19 85 4. Alternative Configurations . . . . . . . . . . . . . . . . . 22 86 4.1. Transmission Parameters . . . . . . . . . . . . . . . . . 22 87 4.2. CoAP over IPv4 . . . . . . . . . . . . . . . . . . . . . 23 88 5. Binding to specific lower-layer APIs . . . . . . . . . . . . 23 89 5.1. Berkeley Socket Interface . . . . . . . . . . . . . . . . 23 90 5.1.1. Responding from the right address . . . . . . . . . . 23 91 5.2. Java . . . . . . . . . . . . . . . . . . . . . . . . . . 24 92 5.3. Multicast detection . . . . . . . . . . . . . . . . . . . 24 93 5.4. DTLS . . . . . . . . . . . . . . . . . . . . . . . . . . 25 94 6. CoAP on various transports . . . . . . . . . . . . . . . . . 25 95 6.1. CoAP over reliable transports . . . . . . . . . . . . . . 25 96 6.2. Translating between transports . . . . . . . . . . . . . 26 97 6.2.1. Transport translation by proxies . . . . . . . . . . 26 98 6.2.2. One-to-one Transport translation . . . . . . . . . . 26 99 7. IANA considerations . . . . . . . . . . . . . . . . . . . . . 27 100 8. Security considerations . . . . . . . . . . . . . . . . . . . 27 101 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 102 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 103 10.1. Normative References . . . . . . . . . . . . . . . . . . 27 104 10.2. Informative References . . . . . . . . . . . . . . . . . 28 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 107 1. Introduction 109 The Constrained Application Protocol [RFC7252] has been designed 110 specifically for machine-to-machine communication in networks with 111 very constrained nodes. Typical application scenarios therefore 112 include building automation, process optimization, and the Internet 113 of Things. The major design objectives have been set on small 114 protocol overhead, robustness against packet loss, and against high 115 latency induced by small bandwidth shares or slow request processing 116 in end nodes. To leverage integration of constrained nodes with the 117 world-wide Internet, the protocol design was led by the REST 118 architectural style that accounts for the scalability and robustness 119 of the Hypertext Transfer Protocol [RFC7230]. 121 Lightweight implementations benefit from this design in many 122 respects: First, the use of Uniform Resource Identifiers (URIs) for 123 naming resources and the transparent forwarding of their 124 representations in a server-stateless request/response protocol make 125 protocol translation to HTTP a straightforward task. Second, the set 126 of protocol elements that are unavoidable for the core protocol, and 127 thus must be implemented on every node, has been kept very small, 128 minimizing the unnecessary accumulation of "optional" features. 129 Options that - when present - are critical for message processing are 130 explicitly marked as such to force immediate rejection of messages 131 with unknown critical options. Third, the syntax of protocol data 132 units is easy to parse and is carefully defined to avoid creation of 133 state in servers where possible. 135 Although these features enable lightweight implementations of the 136 Constrained Application Protocol, there is still a tradeoff between 137 robustness and latency of constrained nodes on one hand and resource 138 demands on the other. For constrained nodes of Class 1 or even 139 Class 2 [RFC7228], the most limiting factors usually are dynamic 140 memory needs, static code size, and energy. Most implementations 141 therefore need to optimize internal buffer usage, omit idle protocol 142 feature, and maximize sleeping cycles. 144 The present document gives possible strategies to solve this tradeoff 145 for very constrained nodes (i.e., Class 1). For this, it provides 146 guidance on correct implementation of the CoAP specification 147 [RFC7252], memory optimizations, and customized protocol parameters. 149 2. Protocol Implementation 151 In the programming styles supported by very simple operating systems 152 as found on constrained nodes, preemptive multi-threading is not an 153 option. Instead, all operations are triggered by an event loop 154 system, e.g., in a send-receive-dispatch cycle. It is also common 155 practice to allocate memory statically to ensure stable behavior, as 156 no memory management unit (MMU) or other abstractions are available. 157 For a CoAP node, the two key parameters for memory usage are the 158 number of (re)transmission buffers and the maximum message size that 159 must be supported by each buffer. Often the maximum message size is 160 set far below the 1280-byte MTU of 6LoWPAN to allow more than one 161 open Confirmable transmission at a time (in particular for parallel 162 observe notifications [I-D.ietf-core-observe]). Note that 163 implementations on constrained platforms often not even support the 164 full MTU. Larger messages must then use blockwise transfers 165 [I-D.ietf-core-block], while a good tradeoff between 6LoWPAN 166 fragmentation and CoAP header overhead must be found. Usually the 167 amount of available free RAM dominates this decision. For Class 1 168 devices, the maximum message size is typically 128 or 256 bytes 169 (blockwise) payload plus an estimate of the maximum header size for 170 the worst case option setting. 172 2.1. Client/Server Model 174 In general, CoAP servers can be implemented more efficiently than 175 clients. REST allows them to keep the communication stateless and 176 piggy-backed responses are not stored for retransmission, saving 177 buffer space. The use of idempotent requests also allows to relax 178 deduplication, which further decreases memory usage. It is also easy 179 to estimate the required maximum size of message buffers, since URI 180 paths, supported options, and maximum payload sizes of the 181 application are known at compile time. Hence, when the application 182 is distributed over constrained and unconstrained nodes, the 183 constrained ones should preferably have the server role. 185 HTTP-based applications have established an inverse model because of 186 the need for simple push notifications: A constrained client uses 187 POST requests to update resources on an unconstrained server whenever 188 an event (e.g., a new sensor reading) is triggered. This requirement 189 is solved by the Observe option [I-D.ietf-core-observe] of CoAP. It 190 allows servers to initiate communication and send push notifications 191 to interested client nodes. This allows a more efficient and also 192 more natural model for CoAP-based applications, where the information 193 source is an origin server, which can also benefit from caching. 195 2.2. Message Processing 197 Apart from the required buffers, message processing is symmetric for 198 clients and servers. First the 4-byte base header has to be parsed 199 and thereby checked if it is a CoAP message. Since the encoding is 200 very dense, only a wrong version or a datagram size smaller than four 201 bytes identify non-CoAP datagrams. These need to be silently 202 ignored. Other message format errors, such as an incomplete datagram 203 or the usage of reserved values, may need to be rejected with a Reset 204 (RST) message (see Section 4.2 and 4.3 of [RFC7252] for details). 205 Next the Token is read based on the TKL field. For the options 206 following, there are two alternatives: either process them on the fly 207 when an option is accessed or initially parse all values into an 208 internal data structure. 210 2.2.1. On-the-fly Processing 212 The advantage of on-the-fly processing is that no additional memory 213 needs to be allocated to store the option values, which are stored 214 efficiently inline in the buffer for incoming messages. Once the 215 message is accepted for further processing, the set of options 216 contained in the received message must be decoded to check for 217 unknown critical options. To avoid multiple passes through the 218 option list, the option parser might maintain a bit-vector where each 219 bit represents an option number that is present in the received 220 request. With the wide and sparse range of option numbers, the 221 number itself cannot be used to indicate the number of left-shift 222 operations to mask the corresponding bit. Hence, an implementation- 223 specific enum of supported options should be used to mask the present 224 options of a message in the bitmap. In addition, the byte index of 225 every option (a direct pointer) can be added to a sparse list (e.g., 226 a one-dimensional array) for fast retrieval. 228 This particularly enables efficient handling of options that might 229 occur more than once such as Uri-Path. In this implementation 230 strategy, the delta is zero for any subsequent path segment, hence 231 the stored byte index for this option (e.g., 11 for Uri-Path) would 232 be overwritten to hold a pointer to only the last occurrence of that 233 option. The Uri-Path can be resolved on the fly, though, and a 234 pointer to the targeted resource stored directly in the sparse list. 236 Once the option list has been processed, all known critical option 237 and all elective options can be masked out in the bit-vector to 238 determine if any unknown critical option was present. If this is the 239 case, this information can be used to create a 4.02 response 240 accordingly. Note that full processing must only be done up to the 241 highest supported option number. Beyond that, only the least 242 significant bit (Critical or Elective) needs to be checked. 243 Otherwise, if all critical options are supported, the sparse list of 244 option pointers is used for further handling of the message. 246 2.2.2. Internal Data Structure 248 Using an internal data structure for all parsed options has an 249 advantage when working on the option values, as they are already in a 250 variable of corresponding type (e.g., an integer in host byte order). 251 The incoming payload and byte strings of the header can be accessed 252 directly in the buffer for incoming messages using pointers (similar 253 to on-the-fly processing). This approach also benefits from a 254 bitmap. Otherwise special values must be reserved to encode an unset 255 option, which might require a larger type than required for the 256 actual value range (e.g., a 32-bit integer instead of 16-bit). 258 Many of the byte strings (e.g., the URI) are usually not required 259 when generating the response. When all important values are copied 260 (e.g., the Token, which needs to be mirrored), the internal data 261 structure facilitates using the buffer for incoming messages also for 262 the assembly of outgoing messages - which can be the shared IP buffer 263 provided by the OS. 265 Setting options for outgoing messages is also easier with an internal 266 data structure. Application developers can set options independent 267 from the option number and do not need to care about the order for 268 the delta encoding. The CoAP encoding is applied in a serialization 269 step before sending. In contrast, assembling outgoing messages with 270 on-the-fly processing requires either extensive memmove operations to 271 insert new options, or restrictions for developers to set options in 272 their correct order. 274 2.3. Message ID Usage 276 Many applications of CoAP use unreliable transports, in particular 277 UDP, which can lose, reorder, and duplicate messages. Although 278 DTLS's replay protection deals with duplication by the network, 279 losses are addressed with DTLS retransmissions only for the handshake 280 protocol and not for the application data protocol. Furthermore, 281 CoAP implementations usually send CON retransmissions in new DTLS 282 records, which are not considered duplicates at the DTLS layer. 284 2.3.1. Duplicate Rejection 286 CoAP's messaging sub-layer has been designed with protocol 287 functionality such that rejection of duplicate messages is always 288 possible. It is realized through the Message IDs (MIDs) and their 289 lifetimes with regard to the message type. 291 Duplicate detection is under the discretion of the recipient (see 292 Section 4.5 of [RFC7252], Section 2.3.3, Section 2.3.4). Where it is 293 desired, the receiver needs to keep track of MIDs to filter the 294 duplicates for at least NON_LIFETIME (145 s). This time also holds 295 for CON messages, since it equals the possible reception window of 296 MAX_TRANSMIT_SPAN + MAX_LATENCY. 298 On the sender side, MIDs of CON messages must not be re-used within 299 the EXCHANGE_LIFETIME; MIDs of NONs respectively within the 300 NON_LIFETIME. In typical scenarios, however, senders will re-use 301 MIDs with intervals far larger than these lifetimes: with sequential 302 assignment of MIDs, coming close to them would require 250 messages 303 per second, much more than the bandwidth of constrained networks 304 would usually allow for. 306 In cases where senders might come closer to the maximum message rate, 307 it is recommended to use more conservative timings for the re-use of 308 MIDs. Otherwise, opposite inaccuracies in the clocks of sender and 309 recipient may lead to obscure message loss. If needed, higher rates 310 can be achieved by using multiple endpoints for sending requests and 311 managing the local MID per remote endpoint instead of a single 312 counter per system (essentially extending the 16-bit message ID by a 313 16-bit port number and/or an 128-bit IP address). In controlled 314 scenarios, such as real-time applications over industrial Ethernet, 315 the protocol parameters can also be tweaked to achieve higher message 316 rates (Section 4.1). 318 2.3.2. MID Namespaces 320 MIDs are assigned under the control of the originator of CON and NON 321 messages, and they do not mix with the MIDs assigned by the peer for 322 CON and NON in the opposite direction. Hence, CoAP implementors need 323 to make sure to manage different namespaces for the MIDs used for 324 deduplication. MIDs of outgoing CONs and NONs belong to the local 325 endpoint; so do the MIDs of incoming ACKs and RSTs. Accordingly, 326 MIDs of incoming CONs and NONs and outgoing ACKs and RSTs belong to 327 the corresponding remote endpoint. Figure 1 depicts a scenario where 328 mixing the namespaces would cause erroneous filtering. 330 Client Server 331 | | 332 | CON [0x1234] | 333 +----------------->| 334 | | 335 | ACK [0x1234] | 336 |<-----------------+ 337 | | 338 | CON [0x4711] | 339 |<-----------------+ Separate response 340 | | 341 | ACK [0x4711] | 342 +----------------->| 343 | | 344 A request follows that uses the same MID as the last separate response 345 | | 346 | CON [0x4711] | 347 +----------------->| 348 Response is filtered | | 349 because MID 0x4711 | ACK [0x4711] | 350 is still in the X<-----------------+ Piggy-backed response 351 deduplication list | | 353 Figure 1: Deduplication must manage the MIDs in different namespace 354 corresponding to their origin endpoints. 356 2.3.3. Relaxation on the Server 358 Using the de-duplication functionality is at the discretion of the 359 receiver: Processing of duplicate messages comes at a cost, but so 360 does the management of the state associated with duplicate rejection. 361 The number of remote endpoints that need to be managed might be vast. 362 This can be costly in particular for less constrained nodes that have 363 throughput in the order of hundreds of thousands requests per second 364 (which needs about 16 GiB of RAM just for duplicate rejection). 365 Deduplication is also heavy for servers on Class 1 devices, as also 366 piggy-backed responses need to be stored for the case that the ACK 367 message is lost. Hence, a receiver may have good reasons to decide 368 not to perform deduplication. This behavior is possible when the 369 application is designed with idempotent operations only and makes 370 good use of the If-Match/If-None-Match options. 372 If duplicate rejection is indeed necessary (e.g., for non-idempotent 373 requests) it is important to control the amount of state that needs 374 to be stored. It can be reduced, for instance, by deduplication at 375 resource level: Knowledge of the application and supported 376 representations can minimize the amount of state that needs to be 377 kept. 379 2.3.4. Relaxation on the Client 381 Duplicate rejection on the client side can be simplified by choosing 382 clever Tokens that are virtually not re-used (e.g., through an 383 obfuscated sequence number in the Token value) and only filter based 384 on the list of open Tokens. If a client wants to re-use Tokens 385 (e.g., the empty Token for optimizations), it requires strict 386 duplicate rejection based on MIDs to avoid the scenario outlined in 387 Figure 2. 389 Client Server 390 | | 391 | CON [0x7a10] | 392 | GET /temp | 393 | (Token 0x23) | 394 +----------------->| 395 | | 396 | ACK [0x7a10] | 397 |<-----------------+ 398 | | 399 ... Time Passes ... 400 | | 401 | CON [0x23bb] | 402 | 4.04 Not Found | 403 | (Token 0x23) | 404 |<-----------------+ 405 | | 406 | ACK [0x23bb] | 407 +--------X | 408 | | 409 | CON [0x7a11] | 410 | GET /resource | 411 | (Token 0x23) | 412 +----------------->| 413 | | 414 | CON [0x23bb] | 415 Causing an implicit | 4.04 Not Found | 416 acknowledgement if | (Token 0x23) | 417 not filtered through X<-----------------+ Retransmission 418 duplicate rejection | | 420 Figure 2: Re-using Tokens requires strict duplicate rejection. 422 2.4. Token Usage 424 Tokens are chosen by the client and help to identify request/response 425 pairs that span several message exchanges (e.g., a separate response, 426 which has a new MID). Servers do not generate Tokens and only mirror 427 what they receive from the clients. Tokens must be unique within the 428 namespace of a client throughout their lifetime. This begins when 429 being assigned to a request and ends when the open request is closed 430 by receiving and matching the final response. Neither empty ACKs nor 431 notifications (i.e., responses carrying the Observe option) terminate 432 the lifetime of a Token. 434 As already mentioned, a clever assignment of Tokens can help to 435 simplify duplicate rejection. Yet this is also important for coping 436 with client crashes. When a client restarts during an open request 437 and (unknowingly) re-uses the same Token, it might match the response 438 from the previous request to the current one. Hence, when only the 439 Token is used for matching, which is always the case for separate 440 responses, randomized Tokens with enough entropy should be used. The 441 8-byte range for Tokens can even allow for one-time usage throughout 442 the lifetime of a client node. When DTLS is used, client crashes/ 443 restarts will lead to a new security handshake, thereby solving the 444 problem of mismatching responses and/or notifications. 446 2.4.1. Tokens for Observe 448 In the case of Observe [I-D.ietf-core-observe], a request will be 449 answered with multiple notifications and it is important to continue 450 keeping track of the Token that was used for the request - its 451 lifetime will end much later. Upon establishing an Observe 452 relationship, the Token is registered at the server. Hence, the 453 client's use of that specific Token is now limited to controlling the 454 Observation relationship. A client can use it to cancel the 455 relationship, which frees the Token upon success (i.e., the message 456 with an Observe Option with the value set to 'deregister' (1) is 457 confirmed with a response; see [I-D.ietf-core-observe] section 3.6). 458 However, the client might never receive the response due to a 459 temporary network outage or worse, a server crash. Although a 460 network outage will also affect notifications so that the Observe 461 garbage collection could apply, the server might simply happen not to 462 send CON notifications during that time. Alternative Observe 463 lifetime models such as Stubbornness(tm) might also keep 464 relationships alive for longer periods. 466 Thus, it is best to carefully choose the Token value used with 467 Observe requests. (The empty value will rarely be applicable.) One 468 option is to assign and re-use dedicated Tokens for each Observe 469 relationship the client will establish. The choice of Token values 470 also is critical in NoSec mode, to limit the effectiveness of 471 spoofing attacks. Here, the recommendation is to use randomized 472 Tokens with a length of at least four bytes (see Section 5.3.1 of 473 [RFC7252]). Thus, dedicated ranges within the 8-byte Token space 474 should be used when in NoSec mode. This also solves the problem of 475 mismatching notifications after a client crash/restart. 477 When the client wishes to reinforce its interest in a resource, maybe 478 not really being sure whether the server has forgotten it or not, the 479 Token value allocated to the Observe relationship is used to re- 480 register that observation (see Section 3.3.1 of 481 [I-D.ietf-core-observe] for details): If the server is still aware of 482 the relationship (an entry with a matching endpoint and token is 483 already present in its list of observers for the resource), it will 484 not add a new relationship but will replace or update the existing 485 one (Section 4.1 of [I-D.ietf-core-observe]). If not, it will simply 486 establish a new registration which of course also uses the Token 487 value. 489 If the client sends an Observe request for the same resource with a 490 new Token, this is not a protocol violation, because the 491 specification allows the client to observe the same resource in a 492 different Observe relationship if the cache-key is different (e.g., 493 requesting a different Content-Format). If the cache-key is not 494 different, though, an additional Observe relationship just wastes the 495 server's resources, and is therefore not allowed; the server might 496 rely on this for its housekeeping. 498 2.4.2. Tokens for Blockwise Transfers 500 In general, blockwise transfers are independent from the Token and 501 are correlated through client endpoint address and server address and 502 resource path (destination URI). Thus, each block may be transferred 503 using a different Token. Still it can be beneficial to use the same 504 Token (it is freed upon reception of a response block) for all 505 blocks, e.g., to easily route received blocks to the same response 506 handler. 508 When Block2 is combined with Observe, notifications only carry the 509 first block and it is up to the client to retrieve the remaining 510 ones. These GET requests do not carry the Observe option and need to 511 use a different Token, since the Token from the notification is still 512 in use. 514 2.5. Transmission States 516 CoAP endpoints must keep transmission state to manage open requests, 517 to handle the different response modes, and to implement reliable 518 delivery at the message layer. The following finite state machines 519 (FSMs) model the transmissions of a CoAP exchange at the request/ 520 response layer and the message layer. These layers are linked 521 through actions. The M_CMD() action triggers a corresponding 522 transition at the message layer and the RR_EVT() action triggers a 523 transition at the request/response layer. The FSMs also use guard 524 conditions to distinguish between information that is only available 525 through the other layer (e.g., whether a request was sent using a CON 526 or NON message). 528 2.5.1. Request/Response Layer 530 Figure 3 depicts the two states at the request/response layer of a 531 CoAP client. When a request is issued, a "reliable_send" or 532 "unreliable_send" is triggered at the message layer. The WAITING 533 state can be left through three transitions: Either the client 534 cancels the request and triggers cancellation of a CON transmission 535 at the message layer, the client receives a failure event from the 536 message layer, or a receive event containing a response. 538 +------------CANCEL-------------------------------+ 539 | / M_CMD(cancel) | 540 | V 541 | +------+ 542 +-------+ -------RR_EVT(fail)--------------------> | | 543 |WAITING| | IDLE | 544 +-------+ -------RR_EVT(rx)[is Response]---------> | | 545 ^ / M_CMD(accept) +------+ 546 | | 547 +--------------------REQUEST----------------------+ 548 / M_CMD((un)reliable_send) 550 Figure 3: CoAP Client Request/Response Layer FSM 552 A server resource can decide at the request/response layer whether to 553 respond with a piggy-backed or a separate response. Thus, there are 554 two busy states in Figure 4, SERVING and SEPARATE. An incoming 555 receive event with a NON request directly triggers the transition to 556 the SEPARATE state. 558 +--------+ <----------RR_EVT(rx)[is NON]---------- +------+ 559 |SEPARATE| | | 560 +--------+ ----------------RESPONSE--------------> | IDLE | 561 ^ / M_CMD((un)reliable_send) | | 562 | +---> +------+ 563 |EMPTY_ACK | | 564 |/M_CMD(accept) | | 565 | | | 566 | | | 567 +--------+ | | 568 |SERVING | --------------RESPONSE------------+ | 569 +--------+ / M_CMD(accept) | 570 ^ | 571 +------------------------RR_EVT(rx)[is CON]--------+ 573 Figure 4: CoAP Server Request/Response Layer FSM 575 2.5.2. Message Layer 577 Figure 5 shows the different states of a CoAP endpoint per message 578 exchange. Besides the linking action RR_EVT(), the message layer has 579 a TX action to send a message. For sending and receiving NONs, the 580 endpoint remains in its CLOSED state. When sending a CON, the 581 endpoint remains in RELIABLE_TX and keeps retransmitting until the 582 transmission times out, it receives a matching RST, the request/ 583 response layer cancels the transmission, or the endpoint receives an 584 implicit acknowledgement through a matching NON or CON. Whenever the 585 endpoint receives a CON, it transitions into the ACK_PENDING state, 586 which can be left by sending the corresponding ACK. 588 +-----------+ <-------M_CMD(reliable_send)-----+ 589 | | / TX(con) \ 590 | | +--------------+ 591 | | ---TIMEOUT(RETX_WINDOW)------> | | 592 |RELIABLE_TX| / RR_EVT(fail) | | 593 | | ---------------------RX_RST--> | | <----+ 594 | | / RR_EVT(fail) | | | 595 +-----------+ ----M_CMD(cancel)------------> | CLOSED | | 596 ^ | | \ \ | | --+ | 597 | | | \ +-------------------RX_ACK---> | | | | 598 +*1+ | \ / RR_EVT(rx) | | | | 599 | +----RX_NON-------------------> +--------------+ | | 600 | / RR_EVT(rx) ^ ^ ^ ^ | | | | | | 601 | | | | | | | | | | | 602 | | | | +*2+ | | | | | 603 | | | +--*3--+ | | | | 604 | | +----*4----+ | | | 605 | +------*5------+ | | 606 | +---------------+ | | 607 | | ACK_PENDING | <--RX_CON-------------+ | 608 +----RX_CON----> | | / RR_EVT(rx) | 609 / RR_EVT(rx) +---------------+ ---------M_CMD(accept)---+ 610 / TX(ack) 612 *1: TIMEOUT(RETX_TIMEOUT) / TX(con) 613 *2: M_CMD(unreliable_send) / TX(non) 614 *3: RX_NON / RR_EVT(rx) 615 *4: RX_RST / REMOVE_OBSERVER 616 *5: RX_ACK 618 Figure 5: CoAP Message Layer FSM 620 T.B.D.: (i) Rejecting messages (can be triggered at message and 621 request/response layer). (ii) ACKs can also be triggered at both 622 layers. 624 2.6. Out-of-band Information 626 The CoAP implementation can also leverage out-of-band information, 627 that might also trigger some of the transitions shown in Section 2.5. 628 In particular ICMP messages can inform about unreachable remote 629 endpoints or whole network outages. This information can be used to 630 pause or cancel ongoing transmission to conserve energy. Providing 631 ICMP information to the CoAP implementation is easier in constrained 632 environments, where developers usually can adapt the underlying OS 633 (or firmware). This is not the case on general purpose platforms 634 that have full-fledged OSes and make use of high-level programming 635 frameworks. 637 The most important ICMP messages are host, network, port, or protocol 638 unreachable errors. After appropriate vetting (cf. [RFC5927]), they 639 should cause the cancellation of ongoing CON transmissions and 640 clearing (or deferral) of Observe relationships. Requests to this 641 destination should be paused for a sensible interval. In addition, 642 the device could indicate of this error through a notification to a 643 management endpoint or external status indicator, since the cause 644 could be a misconfiguration or general unavailability of the required 645 service. Problems reported through the Parameter Problem message are 646 usually caused through a similar fundamental problem. 648 The CoAP specification recommends to ignore Source Quench and Time 649 Exceeded ICMP messages, though. Source Quench messages were 650 originally intended to inform the sender to reduce the rate of 651 packets. However, this mechanism is deprecated through [RFC6633]. 652 CoAP also comes with its own congestion control mechanism, which is 653 already designed conservatively. One advanced mechanism that can be 654 employed for better network utilization is CoCoA, 655 [I-D.bormann-core-cocoa]. Time Exceeded messages often occur during 656 transient routing loops (unless they are caused by a too small 657 initial Hop Limit value). 659 2.7. Programming Model 661 The event-driven approach, which is common in event-loop-based 662 firmware, has also proven very efficient for embedded operating 663 systems [TinyOS], [Contiki]. Note that an OS is not necessarily 664 required and a traditional firmware approach can suffice for Class 1 665 devices. Event-driven systems use split-phase operations (i.e., 666 there are no blocking functions, but functions return and an event 667 handler is called once a long-lasting operation completes) to enable 668 cooperative multi-threading with a single stack. 670 Bringing a Web transfer protocol to constrained environments does not 671 only change the networking of the corresponding systems, but also the 672 programming model. The complexity of event-driven systems can be 673 hidden through APIs that resemble classic RESTful Web service 674 implementations. 676 2.7.1. Client 678 An API for asynchronous requests with response handler functions goes 679 hand-in-hand with the event-driven approach. Synchronous requests 680 with a blocking send function can facilitate applications that 681 require strictly ordered, sequential request execution (e.g., to 682 control a physical process) or other checkpointing (e.g., starting 683 operation only after registration with the resource directory was 684 successful). However, this can also be solved by triggering the next 685 operation in the response handlers. Furthermore, as mentioned in 686 Section 2.1, it is more like that complex control flow is done by 687 more powerful devices and Class 1 devices predominantly run a CoAP 688 server (which might include a minimal client to communicate with a 689 resource directory). 691 2.7.2. Server 693 On CoAP servers, the event-driven nature can be hidden through 694 resource handler abstractions as known from traditional REST 695 frameworks. The following types of RESTful resources have proven 696 useful to provide an intuitive API on constrained event-driven 697 systems: 699 NORMAL A normal resource defined by a static Uri-Path and an 700 associated resource handler function. Allowed methods could 701 already be filtered by the implementation based on flags. This is 702 the basis for all other resource types. 704 PARENT A parent resource manages several sub-resources under a given 705 base path by programmatically evaluating the Uri-Path. Defining a 706 URI template (see [RFC6570]) would be a convenient way to pre- 707 parse arguments given in the Uri-Path. 709 PERIODIC A resource that has an additional handler function that is 710 triggered periodically by the CoAP implementation with a resource- 711 specific interval. It can be used to sample a sensor or perform 712 similar periodic updates of its state. Usually, a periodic 713 resource is observable and sends the notifications by triggering 714 its normal resource handler from the periodic handler. These 715 periodic tasks are quite common for sensor nodes, thus it makes 716 sense to provide this functionality in the CoAP implementation and 717 avoid redundant code in every resource. 719 EVENT An event resource is similar to an periodic resource, only 720 that the second handler is called by an irregular event such as a 721 button. 723 SEPARATE Separate responses are usually used when handling a request 724 takes more time, e.g., due to a slow sensor or UART-based 725 subsystems. To not fully block the system during this time, the 726 handler should also employ split-phase execution: The resource 727 handler returns as soon as possible and an event handler resumes 728 responding when the result is ready. The separate resource type 729 can abstract from the split-phase operation and take care of 730 temporarily storing the request information that is required later 731 in the result handler to send the response (e.g., source address 732 and Token). 734 3. Optimizations 736 3.1. Message Buffers 738 The cooperative multi-threading of an event loop system allows to 739 optimize memory usage through in-place processing and reuse of 740 buffers, in particular the IP buffer provided by the OS or firmware. 742 CoAP servers can significantly benefit from in-place processing, as 743 they can create responses directly in the incoming IP buffer. Note 744 that an embedded OS usually only has a single buffer for incoming and 745 outgoing IP packets. The first few bytes of the basic header are 746 usually parsed into an internal data structure and can be overwritten 747 without harm. Thus, empty ACKs and RST messages can promptly be 748 assembled and sent using the IP buffer. Also when a CoAP server only 749 sends piggy-backed or Non-confirmable responses, no additional buffer 750 is required at the application layer. This, however, requires 751 careful timing so that no incoming data is overwritten before it was 752 processed. Because of cooperative multi-threading, this requirement 753 is relaxed, though. Once the message is sent, the IP buffer can 754 accept new messages again. This does not work for Confirmable 755 messages, however. They need to be stored for retransmission and 756 would block any further IP communication. 758 Depending on the number of requests that can be handled in parallel, 759 an implementation might create a stub response filled with any option 760 that has to be copied from the original request to the separate 761 response, especially the Token option. The drawback of this 762 technique is that the server must be prepared to receive 763 retransmissions of the previous (Confirmable) request to which a new 764 acknowledgement must be generated. If memory is an issue, a single 765 buffer can be used for both tasks: Only the message type and code 766 must be updated, changing the message id is optional. Once the 767 resource representation is known, it is added as new payload at the 768 end of the stub response. Acknowledgements still can be sent as 769 described before as long as no additional options are required to 770 describe the payload. 772 3.2. Retransmissions 774 CoAP's reliable transmissions require the before-mentioned 775 retransmission buffers. Messages, such as the requests of a client, 776 should be stored in serialized form. For servers, retransmissions 777 apply for Confirmable separate responses and Confirmable 778 notifications [I-D.ietf-core-observe]. As separate responses stem 779 from long-lasting resource handlers, the response should be stored 780 for retransmission instead of re-dispatching a stored request (which 781 would allow for updating the representation). For Confirmable 782 notifications, please see Section 2.6, as simply storing the response 783 can break the concept of eventual consistency. 785 String payloads such as JSON require a buffer to print to. By 786 splitting the retransmission buffer into header and payload part, it 787 can be reused. First to generate the payload and then storing the 788 CoAP message by serializing into the same memory. Thus, providing a 789 retransmission for any message type can save the need for a separate 790 application buffer. This, however, requires an estimation about the 791 maximum expected header size to split the buffer and a memmove to 792 concatenate the two parts. 794 For platforms that disable clock tick interrupts in sleep states, the 795 application must take into consideration the clock deviation that 796 occurs during sleep (or ensure to remain in idle state until the 797 message has been acknowledged or the maximum number of 798 retransmissions is reached). Since CoAP allows up to four 799 retransmissions with a binary exponential back-off it could take up 800 to 45 seconds until the send operation is complete. Even in idle 801 state, this means substantial energy consumption for low-power nodes. 802 Implementers therefore might choose a two-step strategy: First, do 803 one or two retransmissions and then, in the later phases of back-off, 804 go to sleep until the next retransmission is due. In the meantime, 805 the node could check for new messages including the acknowledgement 806 for any Confirmable message to send. 808 3.3. Observable Resources 810 For each observer, the server needs to store at least address, port, 811 token, and the last outgoing message ID. The latter is needed to 812 match incoming RST messages and cancel the observe relationship. 814 It is favorable to have one retransmission buffer per observable 815 resource that is shared among all observers. Each notification is 816 serialized once into this buffer and only address, port, and token 817 are changed when iterating over the observer list (note that 818 different token lengths might require realignment). The advantage 819 becomes clear for Confirmable notifications: Instead of one 820 retransmission buffer per observer, only one buffer and only 821 individual retransmission counters and timers in the list entry need 822 to be stored. When the notifications can be sent fast enough, even a 823 single timer would suffice. Furthermore, per-resource buffers 824 simplify the update with a new resource state during open deliveries. 826 3.4. Blockwise Transfers 828 Blockwise transfers have the main purpose of providing fragmentation 829 at the application layer, where partial information can be processed. 830 This is not possible at lower layers such as 6LoWPAN, as only 831 assembled packets can be passed up the stack. While 832 [I-D.ietf-core-block] also anticipates atomic handling of blocks, 833 i.e., only fully received CoAP messages, this is not possible on 834 Class 1 devices. 836 When receiving a blockwise transfer, each block is usually passed to 837 a handler function that for instance performs stream processing or 838 writes the blocks to external memory such as flash. Although there 839 are no restrictions in [I-D.ietf-core-block], it is beneficial for 840 Class 1 devices to only allow ordered transmission of blocks. 841 Otherwise on-the-fly processing would not be possible. 843 When sending a blockwise transfer out of dynamically generated 844 information, Class 1 devices usually do not have sufficient memory to 845 print the full message into a buffer, and slice and send it in a 846 second step. For instance, if the CoRE Link Format at /.well-known/ 847 core is dynamically generated, a generator function is required that 848 generates slices of a large string with a specific offset length (a 849 'sonprintf()'). This functionality is required recurrently and 850 should be included in a library. 852 3.5. Deduplication with Sequential MIDs 854 CoAP's duplicate rejection functionality can be straightforwardly 855 implemented in a CoAP endpoint by storing, for each remote CoAP 856 endpoint ("peer") that it communicates with, a list of recently 857 received CoAP Message IDs (MIDs) along with some timing information. 858 A CoAP message from a peer with a MID that is in the list for that 859 peer can simply be discarded. 861 The timing information in the list can then be used to time out 862 entries that are older than the _expected extent of the re-ordering_, 863 an upper bound for which can be estimated by adding the _potential 864 retransmission window_ ([RFC7252] section "Reliable Messages") and 865 the time packets can stay alive in the network. 867 Such a straightforward implementation is suitable in case other CoAP 868 endpoints generate random MIDs. However, this storage method may 869 consume substantial RAM in specific cases, such as: 871 o many clients are making periodic, non-idempotent requests to a 872 single CoAP server; 874 o one client makes periodic requests to a large number of CoAP 875 servers and/or requests a large number of resources; where servers 876 happen to mostly generate separate CoAP responses (not piggy- 877 backed); 879 For example, consider the first case where the expected extent of re- 880 ordering is 50 seconds, and N clients are sending periodic POST 881 requests to a single CoAP server during a period of high system 882 activity, each on average sending one client request per second. The 883 server would need 100 * N bytes of RAM to store the MIDs only. This 884 amount of RAM may be significant on a RAM-constrained platform. On a 885 number of platforms, it may be easier to allocate some extra program 886 memory (e.g. Flash or ROM) to the CoAP protocol handler process than 887 to allocate extra RAM. Therefore, one may try to reduce RAM usage of 888 a CoAP implementation at the cost of some additional program memory 889 usage and implementation complexity. 891 Some CoAP clients generate MID values by a using a Message ID 892 variable [RFC7252] that is incremented by one each time a new MID 893 needs to be generated. (After the maximum value 65535 it wraps back 894 to 0.) We call this behavior "sequential" MIDs. One approach to 895 reduce RAM use exploits the redundancy in sequential MIDs for a more 896 efficient MID storage in CoAP servers. 898 Naturally such an approach requires, in order to actually reduce RAM 899 usage in an implementation, that a large part of the peers follow the 900 sequential MID behavior. To realize this optimization, the authors 901 therefore RECOMMEND that CoAP endpoint implementers employ the 902 "sequential MID" scheme if there are no reasons to prefer another 903 scheme, such as randomly generated MID values. 905 Security considerations might call for a choice for 906 (pseudo)randomized MIDs. Note however that with truly randomly 907 generated MIDs the probability of MID collision is rather high in use 908 cases as mentioned before, following from the Birthday Paradox. For 909 example, in a sequence of 52 randomly drawn 16-bit values the 910 probability of finding at least two identical values is about 2 911 percent. 913 From here on we consider efficient storage implementations for MIDs 914 in CoAP endpoints, that are optimized to store "sequential" MIDs. 915 Because CoAP messages may be lost or arrive out-of-order, a solution 916 has to take into account that received MIDs of CoAP messages are not 917 actually arriving in a sequential fashion, due to lost or reordered 918 messages. Also a peer might reset and lose its MID counter(s) state. 919 In addition, a peer may have a single Message ID variable used in 920 messages to many CoAP endpoints it communicates with, which partly 921 breaks sequentiality from the receiving CoAP endpoint's perspective. 923 Finally, some peers might use a randomly generated MID values 924 approach. Due to these specific conditions, existing sliding window 925 bitfield implementations for storing received sequence numbers are 926 typically not directly suitable for efficiently storing MIDs. 928 Table 1 shows one example for a per-peer MID storage design: a table 929 with a bitfield of a defined length _K_ per entry to store received 930 MIDs (one per bit) that have a value in the range [MID_i + 1 , MID_i 931 + K]. 933 +----------+----------------+-----------------+ 934 | MID base | K-bit bitfield | base time value | 935 +----------+----------------+-----------------+ 936 | MID_0 | 010010101001 | t_0 | 937 | | | | 938 | MID_1 | 111101110111 | t_1 | 939 | | | | 940 | ... etc. | | | 941 +----------+----------------+-----------------+ 943 Table 1: A per-peer table for storing MIDs based on MID_i 945 The presence of a table row with base MID_i (regardless of the 946 bitfield values) indicates that a value MID_i has been received at a 947 time t_i. Subsequently, each bitfield bit k (0...K-1) in a row i 948 corresponds to a received MID value of MID_i + k + 1. If a bit k is 949 0, it means a message with corresponding MID has not yet been 950 received. A bit 1 indicates such a message has been received already 951 at approximately time t_i. This storage structure allows e.g. with 952 k=64 to store in best case up to 130 MID values using 20 bytes, as 953 opposed to 260 bytes that would be needed for a non-sequential 954 storage scheme. 956 The time values t_i are used for removing rows from the table after a 957 preset timeout period, to keep the MID store small in size and enable 958 these MIDs to be safely re-used in future communications. (Note that 959 the table only stores one time value per row, which therefore needs 960 to be updated on receipt of another MID that is stored as a single 961 bit in this row. As a consequence of only storing one time value per 962 row, older MID entries typically time out later than with a simple 963 per-MID time value storage scheme. The endpoint therefore needs to 964 ensure that this additional delay before MID entries are removed from 965 the table is much smaller than the time period after which a peer 966 starts to re-use MID values due to wrap-around of a peer's MID 967 variable. One solution is to check that a value t_i in a table row 968 is still recent enough, before using the row and updating the value 969 t_i to current time. If not recent enough, e.g. older than N 970 seconds, a new row with an empty bitfield is created.) [Clearly, 971 these optimizations would benefit if the peer were much more 972 conservative about re-using MIDs than currently required in the 973 protocol specification.] 975 The optimization described is less efficient for storing randomized 976 MIDs that a CoAP endpoint may encounter from certain peers. To solve 977 this, a storage algorithm may start in a simple MID storage mode, 978 first assuming that the peer produces non-sequential MIDs. While 979 storing MIDs, a heuristic is then applied based on monitoring some 980 "hit rate", for example, the number of MIDs received that have a Most 981 Significant Byte equal to that of the previous MID divided by the 982 total number of MIDs received. If the hit rate tends towards 1 over 983 a period of time, the MID store may decide that this particular CoAP 984 endpoint uses sequential MIDs and in response improve efficiency by 985 switching its mode to the bitfield based storage. 987 4. Alternative Configurations 989 4.1. Transmission Parameters 991 When a constrained network of CoAP nodes is not communicating over 992 the Internet, for instance because it is shielded by a proxy or a 993 closed deployment, alternative transmission parameters can be used. 994 Consequently, the derived time values provided in [RFC7252] section 995 4.8.2 will also need to be adjusted, since most implementations will 996 encode their absolute values. 998 Static adjustments require a fixed deployment with a constant number 999 or upper bound for the number of nodes, number of hops, and expected 1000 concurrent transmissions. Furthermore, the stability of the wireless 1001 links should be evaluated. ACK_TIMEOUT should be chosen above the 1002 xx% percentile of the round-trip time distribution. 1003 ACK_RANDOM_FACTOR depends on the number of nodes on the network. 1004 MAX_RETRANSMIT should be chosen suitable for the targeted 1005 application. A lower bound for LEISURE can be calculated as 1007 lb_Leisure = S * G / R 1009 where S is the estimated response size, G the group size, and R the 1010 target data transfer rate (see [RFC7252] section 8.2). NSTART and 1011 PROBING_RATE depend on estimated network utilization. If the main 1012 cause for loss are weak links, higher values can be chosen. 1014 Dynamic adjustments will be performed by advanced congestion control 1015 mechanisms such as [I-D.bormann-core-cocoa]. They are required if 1016 the main cause for message loss is network or endpoint congestion. 1017 Semi-dynamic adjustments could be implemented by disseminating new 1018 static transmission parameters to all nodes when the network 1019 configuration changes (e.g., new nodes are added or long-lasting 1020 interference is detected). 1022 4.2. CoAP over IPv4 1024 CoAP was designed for the properties of IPv6, which is dominating in 1025 constrained environments because of the 6LoWPAN adaption layer 1026 [RFC6282]. In particular, the size limitations of CoAP are tailored 1027 to the minimal MTU of 1280 bytes. Until the transition towards IPv6 1028 converges, CoAP nodes might also communicate over IPv4, though. 1029 Sections 4.2 and 4.6 of the base specification [RFC7252] already 1030 provide guidance and implementation notes to handle the smaller 1031 minimal MTUs of IPv4. 1033 Another deployment issue in legacy IPv4 deployments is caused by 1034 Network Address Translators (NATs). The session timeouts are 1035 unpredictable and NATs may close UDP sessions with timeout as short 1036 as 60 seconds. This makes CoAP endpoints behind NATs practically 1037 unreachable, even when they contact the remote endpoint with a public 1038 IP address first. Incorrect behavior may also arise when the NAT 1039 session heuristic changes the external port between two successive 1040 CoAP messages. For the remote endpoint, this will look like two 1041 different CoAP endpoints on the same IP address. Such behavior can 1042 be fatal for the resource directory registration interface. 1044 5. Binding to specific lower-layer APIs 1046 Implementing CoAP on specific lower-layer APIs appears to 1047 consistently bring up certain less-known aspects of these APIs. This 1048 section is intended to alert implementers to such aspects. 1050 5.1. Berkeley Socket Interface 1052 5.1.1. Responding from the right address 1054 In order for a client to recognize a reply (response or 1055 acknowledgement) as coming from the endpoint to which the initiating 1056 packet was addressed, the source IPv6 address of the reply needs to 1057 match the destination address of the initiating packet. 1059 Implementers that have previously written TCP-based applications are 1060 used to binding their server sockets to INADDR_ANY. Any TCP 1061 connection received over such a socket is then more specifically 1062 bound to the source address from which the TCP connection setup was 1063 received; no programmer action is needed for this. 1065 For stateless UDP sockets, more manual work is required. Simply 1066 receiving a packet from a UDP socket bound to INADDR_ANY loses the 1067 information about the destination address; replying to it through the 1068 same socket will use the default address established by the kernel. 1069 Two strategies are available: 1071 o Only use sockets bound to a specific address (not INADDR_ANY). A 1072 system with multiple interfaces (or addresses) will thus need to 1073 bind multiple sockets and send replies back on the same socket the 1074 initiating packet was received on. 1076 o Use IPV6_RECVPKTINFO [RFC3542] to configure the socket, and mirror 1077 back the IPV6_PKTINFO information for the reply (see also 1078 Section 5.1.1.1). 1080 5.1.1.1. Managing interfaces 1082 For some applications, it may further be relevant what interface is 1083 chosen to send to an endpoint, beyond the kernel choosing one that 1084 has a routing table entry for the destination address. E.g., it may 1085 be natural to send out a response or acknowledgment on the same 1086 interface that the packet prompting it was received. The end of the 1087 introduction to section 6 of [RFC3542] describes a simple technique 1088 for this, where that RFC's API (IPV6_PKTINFO) is available. The same 1089 data structure can be used for indicating an interface to send a 1090 packet that is initiating an exchange. (Choosing that interface is 1091 too application-specific to be in scope for the present document.) 1093 5.2. Java 1095 Java provides a wildcard address (0.0.0.0) to bind a socket to all 1096 network interface. This is useful when a server is supposed to 1097 listen on any available interface including the lookback address. 1098 For UDP, and hence CoAP this poses a problem, however, because the 1099 DatagramPacket class does not provide the information to which 1100 address it was sent. When replying through the wildcard socket, the 1101 JVM will pick the default address, which can break the correlation of 1102 messages when the remote endpoint did not send the message to the 1103 default address. This is in particular precarious for IPv6 where it 1104 is common to have multiple IP addresses per network interface. Thus, 1105 it is recommended to bind to all adresses explicitly and manage the 1106 destination address of incoming messages within the CoAP 1107 implementation. 1109 5.3. Multicast detection 1111 Similar to the considerations above, Section 8 of [RFC7252] requires 1112 a node to detect whether a packet that it is going to reply to was 1113 sent to a unicast or to a multicast address. On most platforms, 1114 binding a UDP socket to a unicast address ensures that it only 1115 receives packets addressed to that address. Programmers relying on 1116 this property should ensure that it indeed applies to the platform 1117 they are using. If it does not, IPV6_PKTINFO may, again, help for 1118 Berkeley Socket Interfaces. For Java, explicit management of 1119 different sockets (in this case a MulticastSocket) is required. 1121 5.4. DTLS 1123 CoAPS implementations require access to the authenticated user/device 1124 prinicipal to realize access control for resources. How this 1125 information can be accessed heavily depends on the DTLS 1126 implementation used. Generic and portable CoAP implementations might 1127 want to provide an abstraction layer that can be used by application 1128 developers that implement resource handlers. It is recommended to 1129 keep the API of such an application layer close to popular HTTPS 1130 solutions that are available for the targeted platform, for instance, 1131 mod_ssl or the Java Servlet API. 1133 6. CoAP on various transports 1135 As specified in [RFC7252], CoAP is defined for two underlying 1136 transports: UDP and DTLS. These transports are relatively similar in 1137 terms of the properties they expose to their users. (The main 1138 difference, apart from the increased security, is that DTLS provides 1139 an abstraction of a connection, into which the endpoint abstraction 1140 is placed; in contrast, the UDP endpoint abstraction is based on 1141 four-tuples of IP addresses and ports.) 1143 Recently, the need to carry CoAP over other transports 1144 [I-D.silverajan-core-coap-alternative-transports] has led to 1145 specifications such as CoAP over TLS or TCP 1146 [I-D.tschofenig-core-coap-tcp-tls] or websockets 1147 [I-D.savolainen-core-coap-websockets], or even over non-IP transports 1148 such as SMS [I-D.becker-core-coap-sms-gprs]. This section discusses 1149 considerations that arise when handling these different transports in 1150 an implementation. 1152 6.1. CoAP over reliable transports 1154 To cope with transports without reliable delivery (such as UDP and 1155 DTLS), CoAP defines its own message layer, with acknowledgments, 1156 timers, and retransmission. When CoAP is run over a transport that 1157 provides its own reliability (such as TCP or TLS), running this 1158 machinery would be redundant. Worse, keeping the machinery in place 1159 is likely to lead to interoperability problems as it is unlikely to 1160 be tested as well as on unreliable transports. Therefore, 1161 [I-D.silverajan-core-coap-alternative-transports] was defined by 1162 removing the message layer from CoAP and just running the request/ 1163 response layer directly on top of the reliable transport. This also 1164 leads to a reduced (from the UDP/DTLS 4-byte header) header format. 1166 Conversely, where reliable transports provide a byte stream 1167 abstraction, some form of message delimiting had to be added, which 1168 now needs to be handled in the CoAP implementation. The use of 1169 reliable transports may reduce the disincentive for using messages 1170 larger than optimal link layer packet sizes. Where different message 1171 sizes are chosen by an application for reliable and for unreliable 1172 transports, this can pose additional challenges for translators 1173 (Section 6.2). 1175 Where existing CoAP APIs expose details of the the message layer 1176 (e.g., CON vs. NON, or assigning application layer semantics to 1177 ACKs), using a reliable transport may require additional adjustments. 1179 6.2. Translating between transports 1181 One obvious way to convey CoAP exchanges between different transports 1182 is to run a CoAP proxy that supports both transports. The usual 1183 considerations for proxies apply. Section 6.2.1 discusses some 1184 additional considerations. 1186 Where not much of the functionality of CoAP proxies (such as caching) 1187 is required, a simpler 1:1 translation may be possible, as discussed 1188 in Section 6.2.2. 1190 6.2.1. Transport translation by proxies 1192 (TBD. In particular, point out the obvious: fan-in/fan-out means 1193 that separate message ID and token spaces need to be maintained at 1194 the ends of the proxy.) 1196 One more CoAP specific function of a transport translator proxy may 1197 be to convert between different block sizes, e.g. between a TCP 1198 connection that can tolerate large blocks and UDP over a constrained 1199 node network. 1201 6.2.2. One-to-one Transport translation 1203 A translator with reduced requirements for state maintenance can be 1204 constructed when no fan-in or fan-out is required, and when the 1205 namespace lifetimes of the two sides can be made to coincide. For 1206 this one-to-one translation, there is no need to manage message-ID 1207 and Token value spaces for both sides separately. So, a simple UDP- 1208 to-UDP one-to-one translator could simply copy the messages (among 1209 other applications, this might be useful for translation between IPv4 1210 and IPv6 spaces). Similarly, a DTLS-to-TCP translator could be built 1211 that executes the message layer (deduplication, retransmission) on 1212 the DTLS side, and repackages the CoAP header (add/remove the length 1213 information, and remove/add the message ID and message type) between 1214 the DTLS and the TCP side. 1216 By definition, such a simple one-to-one translator needs to shut down 1217 the connection on one side when the connection on the other side 1218 terminates. However, a UDP-to-TCP one-to-one translator cannot 1219 simply shut down the UDP endpoint when the TCP endpoint vanishes 1220 because the TCP connection closes, so some additional management of 1221 state will be necessary. 1223 7. IANA considerations 1225 This document has no actions for IANA. 1227 8. Security considerations 1229 TBD 1231 9. Acknowledgements 1233 Esko Dijk contributed the sequential MID optimization. Xuan He 1234 provided help creating and improved the state machine charts. 1236 10. References 1238 10.1. Normative References 1240 [I-D.bormann-core-cocoa] 1241 Bormann, C., Betzler, A., Gomez, C., and I. Demirkol, 1242 "CoAP Simple Congestion Control/Advanced", draft-bormann- 1243 core-cocoa-02 (work in progress), July 2014. 1245 [I-D.ietf-core-block] 1246 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 1247 draft-ietf-core-block-17 (work in progress), March 2015. 1249 [I-D.ietf-core-observe] 1250 Hartke, K., "Observing Resources in CoAP", draft-ietf- 1251 core-observe-16 (work in progress), December 2014. 1253 [RFC6282] Hui, J. and P. Thubert, "Compression Format for IPv6 1254 Datagrams over IEEE 802.15.4-Based Networks", RFC 6282, 1255 September 2011. 1257 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1258 and D. Orchard, "URI Template", RFC 6570, March 2012. 1260 [RFC6633] Gont, F., "Deprecation of ICMP Source Quench Messages", 1261 RFC 6633, May 2012. 1263 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1264 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 1265 2014. 1267 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1268 Application Protocol (CoAP)", RFC 7252, June 2014. 1270 10.2. Informative References 1272 [Contiki] Dunkels, A., Groenvall, B., and T. Voigt, "Contiki - a 1273 Lightweight and Flexible Operating System for Tiny 1274 Networked Sensors", Proceedings of the First IEEE Workshop 1275 on Embedded Networked Sensors, November 2004. 1277 [I-D.becker-core-coap-sms-gprs] 1278 Becker, M., Li, K., Kuladinithi, K., and T. Poetsch, 1279 "Transport of CoAP over SMS", draft-becker-core-coap-sms- 1280 gprs-05 (work in progress), August 2014. 1282 [I-D.savolainen-core-coap-websockets] 1283 Savolainen, T., Hartke, K., and B. Silverajan, "CoAP over 1284 WebSockets", draft-savolainen-core-coap-websockets-04 1285 (work in progress), March 2015. 1287 [I-D.silverajan-core-coap-alternative-transports] 1288 Silverajan, B. and T. Savolainen, "CoAP Communication with 1289 Alternative Transports", draft-silverajan-core-coap- 1290 alternative-transports-08 (work in progress), June 2015. 1292 [I-D.tschofenig-core-coap-tcp-tls] 1293 Bormann, C., Lemay, S., Technologies, Z., and H. 1294 Tschofenig, "A TCP and TLS Transport for the Constrained 1295 Application Protocol (CoAP)", draft-tschofenig-core-coap- 1296 tcp-tls-04 (work in progress), June 2015. 1298 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 1299 "Advanced Sockets Application Program Interface (API) for 1300 IPv6", RFC 3542, May 2003. 1302 [RFC5927] Gont, F., "ICMP Attacks against TCP", RFC 5927, July 2010. 1304 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1305 Constrained-Node Networks", RFC 7228, May 2014. 1307 [TinyOS] Levis, P., Madden, S., Polastre, J., Szewczyk, R., 1308 Whitehouse, K., Woo, A., Gay, D., Woo, A., Hill, J., 1309 Welsh, M., Brewer, E., and D. Culler, "TinyOS: An 1310 Operating System for Sensor Networks", Ambient 1311 intelligence, Springer (Berlin Heidelberg), ISBN 1312 978-3-540-27139-0, 2005. 1314 Authors' Addresses 1316 Matthias Kovatsch 1317 ETH Zurich 1318 Universitaetstrasse 6 1319 CH-8092 Zurich 1320 Switzerland 1322 Email: kovatsch@inf.ethz.ch 1324 Olaf Bergmann 1325 Universitaet Bremen TZI 1326 Postfach 330440 1327 D-28359 Bremen 1328 Germany 1330 Email: bergmann@tzi.org 1332 Carsten Bormann (editor) 1333 Universitaet Bremen TZI 1334 Postfach 330440 1335 D-28359 Bremen 1336 Germany 1338 Phone: +49-421-218-63921 1339 Email: cabo@tzi.org