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