idnits 2.17.1 draft-ietf-core-http-mapping-09.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (April 6, 2016) is 2941 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'C-T' is mentioned on line 829, but not defined == Missing Reference: 'C-E' is mentioned on line 815, but not defined == Outdated reference: A later version (-21) exists of draft-ietf-core-block-16 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-04 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-02 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group A. Castellani 3 Internet-Draft University of Padova 4 Intended status: Informational S. Loreto 5 Expires: October 8, 2016 Ericsson 6 A. Rahman 7 InterDigital Communications, LLC 8 T. Fossati 9 Alcatel-Lucent 10 E. Dijk 11 Philips Research 12 April 6, 2016 14 Guidelines for HTTP-CoAP Mapping Implementations 15 draft-ietf-core-http-mapping-09 17 Abstract 19 This document provides reference information for implementing a proxy 20 that performs translation between the HTTP protocol and the CoAP 21 protocol, focusing on the reverse proxy case. It describes how a 22 HTTP request is mapped to a CoAP request and how a CoAP response is 23 mapped back to a HTTP response. Furthermore, it defines a template 24 for URI mapping and provides a set of guidelines for HTTP to CoAP 25 protocol translation and related proxy implementations. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on October 8, 2016. 44 Copyright Notice 46 Copyright (c) 2016 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. Reverse HTTP-CoAP Proxy . . . . . . . . . . . . . . . . . . . 5 64 4. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 5. URI Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 5.1. URI Terminology . . . . . . . . . . . . . . . . . . . . . 8 67 5.2. Default Mapping . . . . . . . . . . . . . . . . . . . . . 8 68 5.2.1. Optional Scheme Omission . . . . . . . . . . . . . . 9 69 5.2.2. Encoding Caveats . . . . . . . . . . . . . . . . . . 9 70 5.3. URI Mapping Template . . . . . . . . . . . . . . . . . . 9 71 5.3.1. Simple Form . . . . . . . . . . . . . . . . . . . . . 10 72 5.3.2. Enhanced Form . . . . . . . . . . . . . . . . . . . . 11 73 5.4. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 13 74 5.4.1. Examples . . . . . . . . . . . . . . . . . . . . . . 13 75 6. Media Type Mapping . . . . . . . . . . . . . . . . . . . . . 15 76 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 15 77 6.2. 'application/coap-payload' Media Type . . . . . . . . . . 17 78 6.3. Loose Media Type Mapping . . . . . . . . . . . . . . . . 17 79 6.4. Media Type to Content Format Mapping Algorithm . . . . . 18 80 6.5. Content Transcoding . . . . . . . . . . . . . . . . . . . 19 81 6.5.1. General . . . . . . . . . . . . . . . . . . . . . . . 19 82 6.5.2. CoRE Link Format . . . . . . . . . . . . . . . . . . 20 83 6.5.3. Diagnostic Messages . . . . . . . . . . . . . . . . . 20 84 7. Response Code Mapping . . . . . . . . . . . . . . . . . . . . 20 85 8. Additional Mapping Guidelines . . . . . . . . . . . . . . . . 23 86 8.1. Caching and Congestion Control . . . . . . . . . . . . . 23 87 8.2. Cache Refresh via Observe . . . . . . . . . . . . . . . . 23 88 8.3. Use of CoAP Blockwise Transfer . . . . . . . . . . . . . 24 89 8.4. CoAP Multicast . . . . . . . . . . . . . . . . . . . . . 25 90 8.5. Timeouts . . . . . . . . . . . . . . . . . . . . . . . . 25 91 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 92 9.1. New 'core.hc' Resource Type . . . . . . . . . . . . . . . 25 93 9.2. New 'coap-payload' Internet Media Type . . . . . . . . . 26 94 10. Security Considerations . . . . . . . . . . . . . . . . . . . 27 95 10.1. Traffic Overflow . . . . . . . . . . . . . . . . . . . . 28 96 10.2. Handling Secured Exchanges . . . . . . . . . . . . . . . 28 97 10.3. URI Mapping . . . . . . . . . . . . . . . . . . . . . . 29 98 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 99 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 100 12.1. Normative References . . . . . . . . . . . . . . . . . . 30 101 12.2. Informative References . . . . . . . . . . . . . . . . . 31 102 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 31 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 105 1. Introduction 107 CoAP [RFC7252] has been designed with the twofold aim to be an 108 application protocol specialized for constrained environments and to 109 be easily used in Representational State Transfer (REST) based 110 architectures such as the Web. The latter goal has led to defining 111 CoAP to easily interoperate with HTTP [RFC7230] through an 112 intermediary proxy which performs cross-protocol conversion. 114 Section 10 of [RFC7252] describes the fundamentals of the CoAP-to- 115 HTTP and the HTTP-to-CoAP cross-protocol mapping process. However, 116 [RFC7252] focuses primarily on specifying the forward proxy scenario, 117 and leaves many aspects of the reverse proxy scenario for future 118 definition. Therefore, a primary goal of this informational document 119 is to define a consistent set of guidelines that an HTTP-to-CoAP 120 reverse proxy implementation should adhere to. The main reason for 121 adhering to such guidelines is to reduce variation between proxy 122 implementations, thereby increasing interoperability between an HTTP 123 endpoint and a CoAP endpoint independent of the reverse proxy that 124 implements the cross-protocol mapping. (For example, a reverse proxy 125 conforming to these guidelines made by vendor A can be easily 126 replaced by a reverse proxy from vendor B that also conforms to the 127 guidelines.) 129 This document is organized as follows: 131 o Section 2 describes terminology to identify proxy types, mapping 132 approaches and proxy deployments; 134 o Section 3 introduces the reverse HTTP-CoAP proxy; 136 o Section 4 lists use cases in which HTTP clients need to contact 137 CoAP servers; 139 o Section 5 introduces a default and advanced HTTP-to-CoAP URI 140 mapping syntax; 142 o Section 6 describes how to map HTTP media types to CoAP content 143 formats and vice versa; 145 o Section 7 describes how to map CoAP responses to HTTP responses; 147 o Section 8 describes additional mapping guidelines related to 148 caching, congestion, timeouts and CoAP blockwise 149 [I-D.ietf-core-block] transfers; 151 o Section 10 discusses possible security impact of HTTP-CoAP 152 protocol mapping. 154 2. Terminology 156 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 157 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 158 "OPTIONAL" in this document are to be interpreted as described in 159 [RFC2119]. 161 HC Proxy: a proxy performing a cross-protocol mapping, in the context 162 of this document a HTTP-CoAP mapping. A Cross-Protocol Proxy can 163 behave as a Forward Proxy, Reverse Proxy or Interception Proxy. In 164 this document we focus on the Reverse Proxy case. 166 Forward Proxy (or Forward HC Proxy): a message forwarding agent that 167 is selected by the client, usually via local configuration rules, to 168 receive requests for some type(s) of absolute URI and to attempt to 169 satisfy those requests via translation to the protocol indicated by 170 the absolute URI. The user decides (is willing to) use the proxy as 171 the forwarding/de-referencing agent for a predefined subset of the 172 URI space. In [RFC7230] this is called a Proxy. [RFC7252] defines 173 Forward-Proxy similarly. 175 Reverse Proxy(or Reverse HC Proxy): as in [RFC7230], a receiving 176 agent that acts as a layer above some other server(s) and translates 177 the received requests to the underlying server's protocol. A Reverse 178 HC Proxy behaves as an origin (HTTP) server on its connection towards 179 the (HTTP) client and as a (CoAP) client on its connection towards 180 the (CoAP) origin server. The (HTTP) client uses the "origin-form" 181 (Section 5.3.1 of [RFC7230]) as a request-target URI. 183 Interception Proxy (or Interception HC Proxy) [RFC3040]: a proxy that 184 receives inbound traffic flows through the process of traffic 185 redirection; transparent to the client. 187 Placement terms: a Server-Side proxy is placed in the same network 188 domain as the server; conversely a Client-Side proxy is placed in the 189 same network domain as the client. In any other case, the proxy is 190 said to be External. 192 Note that a Reverse Proxy appears to a client as an origin server 193 while a Forward Proxy does not, so, when communicating with a Reverse 194 Proxy a client may be unaware it is communicating with a proxy at 195 all. 197 3. Reverse HTTP-CoAP Proxy 199 A reverse HC proxy is accessed by clients only supporting HTTP, and 200 handles their HTTP requests by mapping these to CoAP requests, which 201 are forwarded to CoAP servers; mapping back received CoAP responses 202 to HTTP responses. This mechanism is transparent to the client, 203 which may assume that it is communicating with the intended target 204 HTTP server. In other words, the client accesses the proxy as an 205 origin server using the "origin-form" (Section 5.3.1 of [RFC7230]) as 206 a request target. 208 See Figure 1 for an example deployment scenario. Here a reverse HC 209 proxy is placed server-side, at the boundary of the Constrained 210 Network domain, to avoid sending any HTTP traffic into the 211 Constrained Network and to avoid any (unsecured) CoAP multicast 212 traffic outside the Constrained Network. A DNS server (not shown) is 213 used by the HTTP Client to resolve the IP address of the reverse HC 214 proxy and optionally also used by the reverse HC proxy to resolve IP 215 addresses of CoAP servers. 217 Constrained Network 218 .-------------------. 219 / .------. \ 220 / | CoAP | \ 221 / |server| \ 222 || '------' || 223 || || 224 .--------. HTTP Request .-----------. CoAP Req .------. || 225 | HTTP |----------------->| HTTP-CoAP |----------->| CoAP | || 226 | Client |<-----------------| Proxy |<-----------|Server| || 227 '--------' HTTP Response '-----------' CoAP Resp '------' || 228 || || 229 || .------. || 230 || | CoAP | || 231 \ |server| .------. / 232 \ '------' | CoAP | / 233 \ |server| / 234 \ '------' / 235 '-----------------' 237 Figure 1: Reverse Cross-Protocol Proxy Deployment Scenario 239 Other placement options for the reverse HC proxy are client-side (not 240 shown), which is in the same domain as the HTTP Client; or external, 241 which is both outside the HTTP Client's domain and the CoAP servers' 242 domain. 244 Normative requirements on the translation of HTTP requests to CoAP 245 requests and of the CoAP responses back to HTTP responses are defined 246 in Section 10.2 of [RFC7252]. However, [RFC7252] only considers the 247 case of a Forward HC Proxy in which a client explicitly indicates it 248 targets a request to a CoAP server. This document provides 249 guidelines and more details for the implementation of a Reverse HC 250 Proxy, which should be followed in addition to the normative 251 requirements. Note that most of the guidelines also apply to an 252 Intercepting HC Proxy. 254 4. Use Cases 256 To illustrate in which situations HTTP to CoAP protocol translation 257 may be used, three use cases are described below. 259 1. Legacy building control application without CoAP: A building 260 control application that uses HTTP but not CoAP, can check the status 261 of CoAP sensors and/or actuators via a reverse HC proxy. 263 2. Making sensor data available to 3rd parties on the Web: For 264 demonstration or public interest purposes, a reverse HC proxy may be 265 configured to expose the contents of a CoAP sensor to the world via 266 the web (HTTP and/or HTTPS). Some sensors might only handle secure 267 'coaps' requests, therefore the proxy is configured to translate any 268 request to a 'coaps' secured request. The reverse HC proxy is 269 furthermore configured to only pass through GET requests in order to 270 protect the constrained network. In this way even unattended HTTP 271 clients, such as web crawlers, may index sensor data as regular web 272 pages. 274 3. Smartphone and home sensor: A smartphone can access directly a 275 CoAP home sensor using an authenticated 'https' request, if its home 276 router contains a reverse HC proxy. An HTML5 application on the 277 smartphone can provide a friendly UI to the user using standard 278 (HTTP) networking functions of HTML5. 280 A key point in the above use cases is the expected nature of the URI 281 to be used by the HTTP client initiating the HTTP request to the 282 reverse HC proxy. Specifically, in use case #1, there will be no 283 "coap" or "coaps" related information embedded in the HTTP URI as it 284 is a legacy HTTP client sending the request. So, the HTTP request 285 will follow the processing steps described in all later sections of 286 this document except for the one defined in section Section 5 (i.e., 287 related to embedded "coap" or "coaps" URI processing). Use case #2 288 is also expected to be similar. 290 In contrast, in use case #3, it is expected that the HTTP client will 291 specifically embed "coap" or "coaps" related information in the HTTP 292 URI of the HTTP request to the reverse HC proxy. In this case, the 293 HTTP request will follow the processing steps described in all later 294 sections of this document including the one defined in section 295 Section 5 (i.e., related to embedded "coap" or "coaps" URI 296 processing). 298 5. URI Mapping 300 Though, in principle, a CoAP URI could be directly used by a HTTP 301 client to de-reference a CoAP resource through a reverse HC proxy, 302 the reality is that all major web browsers, networking libraries and 303 command line tools do not allow making HTTP requests using URIs with 304 a scheme "coap" or "coaps". 306 Thus, there is a need for web applications to embed or "pack" a CoAP 307 URI into a HTTP URI so that it can be (non-destructively) transported 308 from the HTTP client to the reverse HC proxy. The reverse HC proxy 309 can then "unpack" the CoAP URI and finally de-reference it via a CoAP 310 request to the target Server. 312 URI Mapping is the process through which the URI of a CoAP resource 313 is transformed into an HTTP URI so that: 315 o the requesting HTTP client can handle it; 317 o the receiving reverse HC proxy can extract the intended CoAP URI 318 unambiguously. 320 To this end, the remainder of this section will identify: 322 o the default mechanism to map a CoAP URI into a HTTP URI; 324 o the URI template format to express a class of CoAP-HTTP URI 325 mapping functions; 327 o the discovery mechanism based on CoRE Link Format [RFC6690] 328 through which clients of a reverse HC proxy can dynamically 329 discover information about the supported URI Mapping Template(s), 330 as well as the URI where the reverse HC proxy function is 331 anchored. 333 5.1. URI Terminology 335 In the remainder of this section, the following terms will be used 336 with a distinctive meaning: 338 HC Proxy URI: 339 URI which refers to the reverse HC proxy function. It 340 conforms to syntax defined in Section 2.7 of [RFC7230]. 342 Target CoAP URI: 343 URI which refers to the (final) CoAP resource that has to be 344 de-referenced. It conforms to syntax defined in Section 6 of 345 [RFC7252]. Specifically, its scheme is either "coap" or 346 "coaps". 348 Hosting HTTP URI: 349 URI that conforms to syntax in Section 2.7 of [RFC7230]. Its 350 authority component refers to a reverse HC proxy, whereas 351 path (and query) component(s) embed the information used by a 352 reverse HC proxy to extract the Target CoAP URI. 354 5.2. Default Mapping 356 The default mapping is for the Target CoAP URI to be appended as-is 357 to the HC Proxy URI, to form the Hosting HTTP URI. This is the URI 358 that will then be sent by the HTTP client in the HTTP request to the 359 reverse HC proxy. 361 For example: given a HC Proxy URI http://p.example.com/hc and a 362 Target CoAP URI coap://s.example.com/light, the resulting Hosting 363 HTTP URI would be http://p.example.com/hc/coap://s.example.com/light. 365 Provided a correct Target CoAP URI, the Hosting HTTP URI resulting 366 from the default mapping is always syntactically correct. 367 Furthermore, the Target CoAP URI can always be extracted 368 unambiguously from the Hosting HTTP URI. Also, it is worth noting 369 that, using the default mapping, a query component in the target CoAP 370 resource URI is naturally encoded into the query component of the 371 Hosting URI, e.g.: coap://s.example.com/light?dim=5 becomes 372 http://p.example.com/hc/coap://s.example.com/light?dim=5. 374 There is no default for the HC Proxy URI. Therefore, it is either 375 known in advance, e.g. as a configuration preset, or dynamically 376 discovered using the mechanism described in Section 5.4. 378 The default URI mapping function SHOULD be implemented and activated 379 by default in a reverse HC proxy, unless there are valid reasons, 380 e.g. application specific, to use a different mapping function. 382 5.2.1. Optional Scheme Omission 384 When found in a Hosting HTTP URI, the scheme (i.e., "coap" or 385 "coaps"), the scheme component delimiter (":"), and the double slash 386 ("//") preceding the authority MAY be omitted. In such case, a local 387 default - not defined by this document - applies. 389 So, http://p.example.com/hc/s.coap.example.com/foo could either 390 represent the target coap://s.coap.example.com/foo or 391 coaps://s.coap.example.com/foo depending on application specific 392 presets. 394 5.2.2. Encoding Caveats 396 When the authority of the Target CoAP URI is given as an IPv6address, 397 then the surrounding square brackets must be percent-encoded in the 398 Hosting HTTP URI, in order to comply with the syntax defined in 399 Section 3.3. of [RFC3986] for a URI path segment. E.g.: 400 coap://[2001:db8::1]/light?on becomes 401 http://p.example.com/hc/coap://%5B2001:db8::1%5D/light?on. 403 Everything else can be safely copied verbatim from the Target CoAP 404 URI to the Hosting HTTP URI. 406 5.3. URI Mapping Template 408 This section defines a format for the URI template [RFC6570] used by 409 a reverse HC proxy to inform its clients about the expected syntax 410 for the Hosting HTTP URI. This will then be used by the HTTP client 411 to construct the URI to be sent in the HTTP request to the reverse HC 412 proxy. 414 When instantiated, an URI Mapping Template is always concatenated to 415 a HC Proxy URI provided by the reverse HC proxy via discovery (see 416 Section 5.4), or by other means. 418 A simple form (Section 5.3.1) and an enhanced form (Section 5.3.2) 419 are provided to fit different users' requirements. 421 Both forms are expressed as level 2 URI templates [RFC6570] to take 422 care of the expansion of values that are allowed to include reserved 423 URI characters. The syntax of all URI formats is specified in this 424 section in Augmented Backus-Naur Form (ABNF) [RFC5234]. 426 5.3.1. Simple Form 428 The simple form MUST be used for mappings where the Target CoAP URI 429 is going to be copied (using rules of Section 5.2.2) at some fixed 430 position into the Hosting HTTP URI. 432 The following template variables MUST be used in mutual exclusion in 433 a template definition: 435 cu = coap-URI ; from [RFC7252], Section 6.1 436 su = coaps-URI ; from [RFC7252], Section 6.2 437 tu = cu / su 439 The same considerations as in Section 5.2.1 apply, in that the CoAP 440 scheme may be omitted from the Hosting HTTP URI. 442 5.3.1.1. Examples 444 All the following examples (given as a specific URI mapping template, 445 a Target CoAP URI, and the produced Hosting HTTP URI) use 446 http://p.example.com/hc as the HC Proxy URI. Note that these 447 examples all define mapping templates that deviate from the default 448 template of Section 5.2 to be able to illustrate the use of the above 449 template variables. 451 1. "coap" URI is a query argument of the Hosting HTTP URI: 453 ?coap_target_uri={+cu} 455 coap://s.example.com/light 457 http://p.example.com/hc?coap_target_uri=coap://s.example.com/light 459 2. "coaps" URI is a query argument of the Hosting HTTP URI: 461 ?coaps_target_uri={+su} 463 coaps://s.example.com/light 465 http://p.example.com/hc?coaps_target_uri=coaps://s.example.com/light 467 3. Target CoAP URI as a query argument of the Hosting HTTP URI: 469 ?target_uri={+tu} 471 coap://s.example.com/light 473 http://p.example.com/hc?target_uri=coap://s.example.com/light 475 or 477 coaps://s.example.com/light 479 http://p.example.com/hc?target_uri=coaps://s.example.com/light 481 4. Target CoAP URI in the path component of the Hosting HTTP URI 482 (i.e., the default URI Mapping template): 484 /{+tu} 486 coap://s.example.com/light 488 http://p.example.com/hc/coap://s.example.com/light 490 or 492 coaps://s.example.com/light 494 http://p.example.com/hc/coaps://s.example.com/light 496 5. "coap" URI is a query argument of the Hosting HTTP URI; client 497 decides to omit scheme because a default scheme is agreed 498 beforehand between client and proxy: 500 ?coap_uri={+cu} 502 coap://s.example.com/light 504 http://p.example.com/hc?coap_uri=s.example.com/light 506 5.3.2. Enhanced Form 508 The enhanced form can be used to express more sophisticated mappings, 509 i.e., those that do not fit into the simple form. 511 There MUST be at most one instance of each of the following template 512 variables in a template definition: 514 s = "coap" / "coaps" ; from [RFC7252], Sections 6.1 and 6.2 515 hp = host [":" port] ; from [RFC3986] Sections 3.2.2 and 3.2.3 516 p = path-abempty ; from [RFC3986] Section 3.3 517 q = query ; from [RFC3986] Section 3.4 518 qq = [ "?" query ] ; qq is empty iff 'query' is empty 520 5.3.2.1. Examples 522 All the following examples (given as a specific URI mapping template, 523 a Target CoAP URI, and the produced Hosting HTTP URI) use 524 http://p.example.com/hc as the HC Proxy URI. 526 1. Target CoAP URI components in path segments, and optional query 527 in query component: 529 {+s}{+hp}{+p}{+qq} 531 coap://s.example.com/light 533 http://p.example.com/hc/coap/s.example.com/light 535 or 537 coap://s.example.com/light?on 539 http://p.example.com/hc/coap/s.example.com/light?on 541 2. Target CoAP URI components split in individual query arguments: 543 ?s={+s}&hp={+hp}&p={+p}&q={+q} 545 coap://s.example.com/light 547 http://p.example.com/hc?s=coap&hp=s.example.com&p=/light&q= 549 or 551 coaps://s.example.com/light?on 553 http://p.example.com/hc?s=coaps&hp=s.example.com&p=/light&q=on 555 5.4. Discovery 557 In order to accommodate site specific needs while allowing third 558 parties to discover the proxy function, the reverse HC proxy SHOULD 559 publish information related to the location and syntax of the reverse 560 HC proxy function using the CoRE Link Format [RFC6690] interface. 562 To this aim a new Resource Type, "core.hc", is defined in this 563 document. It can be used as the value for the "rt" attribute in a 564 query to the /.well-known/core in order to locate the URI where the 565 reverse HC proxy function is anchored, i.e. the HC Proxy URI. 567 Along with it, the new target attribute "hct" is defined in this 568 document. This attribute MAY be returned in a "core.hc" link to 569 provide the URI Mapping Template associated to the mapping resource. 570 The default template given in Section 5.2, i.e., {+tu}, MUST be 571 assumed if no "hct" attribute is found in the returned link. If a 572 "hct" attribute is present in the returned link, then a client MUST 573 use it to create the Hosting HTTP URI. 575 The URI mapping SHOULD be discoverable (as specified in [RFC6690]) on 576 both the HTTP and the CoAP side of the reverse HC proxy, with one 577 important difference: on the CoAP side the link associated to the 578 "core.hc" resource needs an explicit anchor referring to the HTTP 579 origin, while on the HTTP interface the link context is already the 580 HTTP origin carried in the request's Host header, and doesn't have to 581 be made explicit. 583 5.4.1. Examples 585 o The first example exercises the CoAP interface, and assumes that 586 the default template, {+tu}, is used. For example, in use case #3 587 in section Section 4, the smartphone may discover the public 588 reverse HC proxy before leaving the home network. Then when 589 outside the home network, the smartphone will be able to query the 590 appropriate home sensor. 592 Req: GET coap://[ff02::1]/.well-known/core?rt=core.hc 594 Res: 2.05 Content 595 ;anchor="http://p.example.com";rt="core.hc" 597 o The second example - also on the CoAP side of the reverse HC proxy 598 - uses a custom template, i.e., one where the CoAP URI is carried 599 inside the query component, thus the returned link carries the URI 600 template to be used in an explicit "hct" attribute: 602 Req: GET coap://[ff02::1]/.well-known/core?rt=core.hc 604 Res: 2.05 Content 605 ;anchor="http://p.example.com"; 606 rt="core.hc";hct="?uri={+tu}" 608 On the HTTP side, link information can be serialized in more than one 609 way: 611 o using the 'application/link-format' content type: 613 Req: GET /.well-known/core?rt=core.hc HTTP/1.1 614 Host: p.example.com 616 Res: HTTP/1.1 200 OK 617 Content-Type: application/link-format 618 Content-Length: 18 620 ;rt="core.hc" 622 o using the 'application/link-format+json' content type as defined 623 in [I-D.ietf-core-links-json]: 625 Req: GET /.well-known/core?rt=core.hc HTTP/1.1 626 Host: p.example.com 628 Res: HTTP/1.1 200 OK 629 Content-Type: application/link-format+json 630 Content-Length: 31 632 [{"href":"/hc","rt":"core.hc"}] 634 o using the Link header: 636 Req: GET /.well-known/core?rt=core.hc HTTP/1.1 637 Host: p.example.com 639 Res: HTTP/1.1 200 OK 640 Link: ;rt="core.hc" 642 o A reverse HC proxy may expose two different HC Proxy URIs to 643 differentiate between Target CoAP resources in the "coap" and 644 "coaps" scheme: 646 Req: GET /.well-known/core?rt=core.hc 647 Host: p.example.com 649 Res: HTTP/1.1 200 OK 650 Content-Type: application/link-format+json 651 Content-Length: 111 653 [ 654 {"href":"/hc/plaintext","rt":"core.hc","hct":"{+cu}"}, 655 {"href":"/hc/secure","rt":"core.hc","hct":"{+su}"} 656 ] 658 6. Media Type Mapping 660 6.1. Overview 662 A reverse HC proxy needs to translate HTTP media types 663 (Section 3.1.1.1 of [RFC7231]) and content encodings (Section 3.1.2.2 664 of [RFC7231]) into CoAP content formats (Section 12.3 of [RFC7252]) 665 and vice versa. 667 Media type translation can happen in GET, PUT or POST requests going 668 from HTTP to CoAP, and in 2.xx (i.e., successful) responses going 669 from CoAP to HTTP. Specifically, PUT and POST need to map both the 670 Content-Type and Content-Encoding HTTP headers into a single CoAP 671 Content-Format option, whereas GET needs to map Accept and Accept- 672 Encoding HTTP headers into a single CoAP Accept option. To generate 673 the HTTP response, the CoAP Content-Format option is mapped back to a 674 suitable HTTP Content-Type and Content-Encoding combination. 676 An HTTP request carrying a Content-Type and Content-Encoding 677 combination which the reverse HC proxy is unable to map to an 678 equivalent CoAP Content-Format, SHALL elicit a 415 (Unsupported Media 679 Type) response by the reverse HC proxy. 681 On the content negotiation side, failure to map Accept and Accept-* 682 headers SHOULD be silently ignored: the reverse HC proxy SHOULD 683 therefore forward as a CoAP request with no Accept option. The 684 reverse HC proxy thus disregards the Accept/Accept-* header fields by 685 treating the response as if it is not subject to content negotiation, 686 as mentioned in Sections 5.3.* of [RFC7231]. However, a reverse HC 687 proxy implementation is free to attempt mapping a single Accept 688 header in a GET request to multiple CoAP GET requests, each with a 689 single Accept option, which are then tried in sequence until one 690 succeeds. Note that an HTTP Accept */* MUST be mapped to a CoAP 691 request without Accept option. 693 While the CoAP to HTTP direction has always a well defined mapping 694 (with the exception examined in Section 6.2), the HTTP to CoAP 695 direction is more problematic because the source set, i.e., 696 potentially 1000+ IANA registered media types, is much bigger than 697 the destination set, i.e., the mere 6 values initially defined in 698 Section 12.3 of [RFC7252]. 700 Depending on the tight/loose coupling with the application(s) for 701 which it proxies, the reverse HC proxy could implement different 702 media type mappings. 704 When tightly coupled, the reverse HC proxy knows exactly which 705 content formats are supported by the applications, and can be strict 706 when enforcing its forwarding policies in general, and the media type 707 mapping in particular. 709 On the other side, when the reverse HC proxy is a general purpose 710 application layer gateway, being too strict could significantly 711 reduce the amount of traffic that it'd be able to successfully 712 forward. In this case, the "loose" media type mapping detailed in 713 Section 6.3 MAY be implemented. 715 The latter grants more evolution of the surrounding ecosystem, at the 716 cost of allowing more attack surface. In fact, as a result of such 717 strategy, payloads would be forwarded more liberally across the 718 unconstrained/constrained network boundary of the communication path. 719 Therefore, when applied, other forms of access control must be set in 720 place to avoid unauthorized users to deplete or abuse systems and 721 network resources. 723 6.2. 'application/coap-payload' Media Type 725 If the reverse HC proxy receives a CoAP response with a Content- 726 Format that it does not recognize (e.g. because the value has been 727 registered after the proxy has been deployed, or the CoAP server uses 728 an experimental value which is not registered), then the reverse HC 729 proxy SHALL return a generic "application/coap-payload" media type 730 with numeric parameter "cf" as defined in Section 9.2. 732 For example, the CoAP content format '60' ("application/cbor") would 733 be represented by "application/coap-payload;cf=60", if the reverse HC 734 Proxy doesn't recognize the content format '60'. 736 A HTTP client may use the media type "application/coap-payload" as a 737 means to send a specific content format to a CoAP server via a 738 reverse HC Proxy if the client has determined that the reverse HC 739 Proxy does not directly support the type mapping it needs. This case 740 may happen when dealing for example with newly registered, yet to be 741 registered, or experimental CoAP content formats. 743 6.3. Loose Media Type Mapping 745 By structuring the type information in a super-class (e.g. "text") 746 followed by a finer grained sub-class (e.g. "html"), and optional 747 parameters (e.g. "charset=utf-8"), Internet media types provide a 748 rich and scalable framework for encoding the type of any given 749 entity. 751 This approach is not applicable to CoAP, where Content Formats 752 conflate an Internet media type (potentially with specific 753 parameters) and a content encoding into one small integer value. 755 To remedy this loss of flexibility, we introduce the concept of a 756 "loose" media type mapping, where media types that are 757 specializations of a more generic media type can be aliased to their 758 super-class and then mapped (if possible) to one of the CoAP content 759 formats. For example, "application/soap+xml" can be aliased to 760 "application/xml", which has a known conversion to CoAP. In the 761 context of this "loose" media type mapping, "application/octet- 762 stream" can be used as a fallback when no better alias is found for a 763 specific media type. 765 Table 1 defines the default lookup table for the "loose" media type 766 mapping. Given an input media type, the table returns its best 767 generalized media type using the most specific match i.e. the table 768 entries are compared to the input in top to bottom order until an 769 entry matches. 771 +---------------------+--------------------------+ 772 | Internet media type | Generalized media type | 773 +---------------------+--------------------------+ 774 | application/*+xml | application/xml | 775 | application/*+json | application/json | 776 | text/xml | application/xml | 777 | text/* | text/plain | 778 | */* | application/octet-stream | 779 +---------------------+--------------------------+ 781 Table 1: Media type generalization lookup table 783 The "loose" media type mapping is an OPTIONAL feature. 784 Implementations supporting this kind of mapping should provide a 785 flexible way to define the set of media type generalizations allowed. 787 6.4. Media Type to Content Format Mapping Algorithm 789 This section defines the algorithm used to map an HTTP Internet media 790 type to its correspondent CoAP content format. 792 The algorithm uses the mapping table defined in Section 12.3 of 793 [RFC7252] plus, possibly, any locally defined extension of it. 794 Optionally, the table and lookup mechanism described in Section 6.3 795 can be used if the implementation chooses so. 797 Note that the algorithm may have side effects on the associated 798 representation (see also Section 6.5). 800 In the following: 802 o C-T, C-E, and C-F stand for the values of the Content-Type (or 803 Accept) HTTP header, Content-Encoding (or Accept-Encoding) HTTP 804 header, and Content-Format CoAP option respectively. 806 o If C-E is not given it is assumed to be "identity". 808 o MAP is the mandatory lookup table, GMAP is the optional 809 generalized table. 811 INPUT: C-T and C-E 812 OUTPUT: C-F or Fail 814 1. if no C-T: return Fail 815 2. C-F = MAP[C-T, C-E] 816 3. if C-F is not None: return C-F 817 4. if C-E is not "identity": 818 5. if C-E is supported (e.g. gzip): 819 6. decode the representation accordingly 820 7. set C-E to "identity" 821 8. else: 822 9. return Fail 823 10. repeat steps 2. and 3. 824 11. if C-T allows a non-lossy transformation into \ 825 12. one of the supported C-F: 826 13. transcode the representation accordingly 827 14. return C-F 828 15. if GMAP is defined: 829 16. C-F = GMAP[C-T] 830 17. if C-F is not None: return C-F 831 18. return Fail 833 Figure 2 835 6.5. Content Transcoding 837 6.5.1. General 839 Payload content transcoding (e.g. see steps 11-14 of Figure 2) is an 840 OPTIONAL feature. Implementations supporting this feature should 841 provide a flexible way to define the set of transcodings allowed. 843 As noted in Section 6.4, the process of mapping the media type can 844 have side effects on the forwarded entity body. This may be caused 845 by the removal or addition of a specific content encoding, or because 846 the reverse HC proxy decides to transcode the representation to a 847 different (compatible) format. The latter proves useful when an 848 optimized version of a specific format exists. For example an XML- 849 encoded resource could be transcoded to Efficient XML Interchange 850 (EXI) format, or a JSON-encoded resource into CBOR [RFC7049], 851 effectively achieving compression without losing any information. 853 However, it should be noted that in certain cases, transcoding can 854 lose information in a non-obvious manner. For example, encoding an 855 XML document using schema-informed EXI encoding leads to a loss of 856 information when the destination does not know the exact schema 857 version used by the encoder, which means that whenever the reverse HC 858 proxy transcodes an application/XML to application/EXI in-band 859 metadata could be lost. Therefore, the implementer should always 860 carefully verify such lossy payload transformations before triggering 861 the transcoding. 863 6.5.2. CoRE Link Format 865 The CoRE Link Format [RFC6690] is a set of links (i.e., URIs and 866 their formal relationships) which is carried as content payload in a 867 CoAP response. These links usually include CoAP URIs that might be 868 translated by the reverse HC proxy to the correspondent HTTP URIs 869 using the implemented URI mapping function (see Section 5). Such a 870 process would inspect the forwarded traffic and attempt to re-write 871 the body of resources with an application/link-format media type, 872 mapping the embedded CoAP URIs to their HTTP counterparts. Some 873 potential issues with this approach are: 875 1. The client may be interested to retrieve original (unaltered) 876 CoAP payloads through the reverse HC proxy, not modified 877 versions. 879 2. Tampering with payloads is incompatible with resources that are 880 integrity protected (although this is a problem with transcoding 881 in general). 883 3. The reverse HC proxy needs to fully understand [RFC6690] syntax 884 and semantics, otherwise there is an inherent risk to corrupt the 885 payloads. 887 Therefore, CoRE Link Format payload should only be transcoded at the 888 risk and discretion of the proxy implementer. 890 6.5.3. Diagnostic Messages 892 CoAP responses may, in certain error cases, contain a diagnostic 893 message in the payload explaining the error situation, as described 894 in Section 5.5.2 of [RFC7252]. If present, the CoAP response 895 diagnostic payload SHOULD be copied in the HTTP response body. The 896 CoAP diagnostic message MUST NOT be copied into the HTTP reason- 897 phrase, since it potentially contains CR-LF characters which are 898 incompatible with HTTP reason-phrase syntax. 900 7. Response Code Mapping 902 Table 2 defines the HTTP response status codes to which each CoAP 903 response code SHOULD be mapped. Multiple appearances of a HTTP 904 status code in the second column indicates multiple equivalent HTTP 905 responses are possible based on the same CoAP response code, 906 depending on the conditions cited in the Notes (third column and text 907 below table). 909 +-----------------------------+-----------------------------+-------+ 910 | CoAP Response Code | HTTP Status Code | Notes | 911 +-----------------------------+-----------------------------+-------+ 912 | 2.01 Created | 201 Created | 1 | 913 | 2.02 Deleted | 200 OK | 2 | 914 | | 204 No Content | 2 | 915 | 2.03 Valid | 304 Not Modified | 3 | 916 | | 200 OK | 4 | 917 | 2.04 Changed | 200 OK | 2 | 918 | | 204 No Content | 2 | 919 | 2.05 Content | 200 OK | | 920 | 4.00 Bad Request | 400 Bad Request | | 921 | 4.01 Unauthorized | 403 Forbidden | 5 | 922 | 4.02 Bad Option | 400 Bad Request | 6 | 923 | 4.02 Bad Option | 500 Internal Server Error | 6 | 924 | 4.03 Forbidden | 403 Forbidden | | 925 | 4.04 Not Found | 404 Not Found | | 926 | 4.05 Method Not Allowed | 400 Bad Request | 7 | 927 | 4.06 Not Acceptable | 406 Not Acceptable | | 928 | 4.12 Precondition Failed | 412 Precondition Failed | | 929 | 4.13 Request Ent. Too Large | 413 Request Repr. Too Large | | 930 | 4.15 Unsupported Media Type | 415 Unsupported Media Type | | 931 | 5.00 Internal Server Error | 500 Internal Server Error | | 932 | 5.01 Not Implemented | 501 Not Implemented | | 933 | 5.02 Bad Gateway | 502 Bad Gateway | | 934 | 5.03 Service Unavailable | 503 Service Unavailable | 8 | 935 | 5.04 Gateway Timeout | 504 Gateway Timeout | | 936 | 5.05 Proxying Not Supported | 502 Bad Gateway | 9 | 937 +-----------------------------+-----------------------------+-------+ 939 Table 2: CoAP-HTTP Response Code Mappings 941 Notes: 943 1. A CoAP server may return an arbitrary format payload along with 944 this response. If present, this payload MUST be returned as 945 entity in the HTTP 201 response. Section 7.3.2 of [RFC7231] does 946 not put any requirement on the format of the entity. (In the 947 past, [RFC2616] did.) 949 2. The HTTP code is 200 or 204 respectively for the case that a CoAP 950 server returns a payload or not. [RFC7231] Section 5.3 requires 951 code 200 in case a representation of the action result is 952 returned for DELETE/POST/PUT, and code 204 if not. Hence, a 953 proxy MUST transfer any CoAP payload contained in a CoAP 2.02 954 response to the HTTP client using a 200 OK response. 956 3. HTTP code 304 (Not Modified) is sent if the HTTP client performed 957 a conditional HTTP request and the CoAP server responded with 958 2.03 (Valid) to the corresponding CoAP validation request. Note 959 that Section 4.1 of [RFC7232] puts some requirements on header 960 fields that must be present in the HTTP 304 response. 962 4. A 200 response to a CoAP 2.03 occurs only when the reverse HC 963 proxy, for efficiency reasons, is running a local cache. An 964 unconditional HTTP GET which produces a cache-hit, could trigger 965 a re-validation (i.e. a conditional GET) on the CoAP side. The 966 proxy receiving 2.03 updates the freshness of its cached 967 representation and returns it to the HTTP client. 969 5. A HTTP 401 Unauthorized (Section 3.1 of [RFC7235]) response is 970 not applicable because there is no equivalent in CoAP of WWW- 971 Authenticate which is mandatory in a HTTP 401 response. 973 6. If the proxy has a way to determine that the Bad Option is due to 974 the straightforward mapping of a client request header into a 975 CoAP option, then returning HTTP 400 (Bad Request) is 976 appropriate. In all other cases, the proxy MUST return HTTP 500 977 (Internal Server Error) stating its inability to provide a 978 suitable translation to the client's request. 980 7. A CoAP 4.05 (Method Not Allowed) response SHOULD normally be 981 mapped to a HTTP 400 (Bad Request) code, because the HTTP 405 982 response would require specifying the supported methods - which 983 are generally unknown. In this case the reverse HC Proxy SHOULD 984 also return a HTTP reason-phrase in the HTTP status line that 985 starts with the string "CoAP server returned 4.05" in order to 986 facilitate troubleshooting. However, if the reverse HC proxy has 987 more granular information about the supported methods for the 988 requested resource (e.g. via a Resource Directory 989 ([I-D.ietf-core-resource-directory])) then it MAY send back a 990 HTTP 405 (Method Not Allowed) with a properly filled in "Allow" 991 response-header field (Section 7.4.1 of [RFC7231]). 993 8. The value of the HTTP "Retry-After" response-header field is 994 taken from the value of the CoAP Max-Age Option, if present. 996 9. This CoAP response can only happen if the proxy itself is 997 configured to use a CoAP forward-proxy (Section 5.7 of [RFC7252]) 998 to execute some, or all, of its CoAP requests. 1000 8. Additional Mapping Guidelines 1002 8.1. Caching and Congestion Control 1004 A reverse HC proxy should cache CoAP responses, and reply whenever 1005 applicable with a cached representation of the requested resource. 1007 If the HTTP client drops the connection after the HTTP request was 1008 made, a reverse HC proxy should wait for the associated CoAP response 1009 and cache it if possible. Subsequent requests to the reverse HC 1010 proxy for the same resource can use the result present in cache, or, 1011 if a response has still to come, the HTTP requests will wait on the 1012 open CoAP request. 1014 According to [RFC7252], a proxy must limit the number of outstanding 1015 requests to a given CoAP server to NSTART. To limit the amount of 1016 aggregate traffic to a constrained network, the reverse HC proxy 1017 should also put a limit on the number of concurrent CoAP requests 1018 pending on the same constrained network; further incoming requests 1019 may either be queued or dropped (returning 503 Service Unavailable). 1020 This limit and the proxy queueing/dropping behavior should be 1021 configurable. 1023 Highly volatile resources that are being frequently requested may be 1024 observed [RFC7641] by the reverse HC proxy to keep their cached 1025 representation fresh while minimizing the amount of CoAP traffic in 1026 the constrained network. See Section 8.2. 1028 8.2. Cache Refresh via Observe 1030 There are cases where using the CoAP observe protocol [RFC7641] to 1031 handle proxy cache refresh is preferable to the validation mechanism 1032 based on ETag as defined in [RFC7252]. Such scenarios include, but 1033 are not limited to, sleepy CoAP nodes -- with possibly high variance 1034 in requests' distribution -- which would greatly benefit from a 1035 server driven cache update mechanism. Ideal candidates for CoAP 1036 observe are also crowded or very low throughput networks, where 1037 reduction of the total number of exchanged messages is an important 1038 requirement. 1040 This subsection aims at providing a practical evaluation method to 1041 decide whether refreshing a cached resource R is more efficiently 1042 handled via ETag validation or by establishing an observation on R. 1044 Let T_R be the mean time between two client requests to resource R, 1045 let T_C be the mean time between two representation changes of R, and 1046 let M_R be the mean number of CoAP messages per second exchanged to 1047 and from resource R. If we assume that the initial cost for 1048 establishing the observation is negligible, an observation on R 1049 reduces M_R iff T_R < 2*T_C with respect to using ETag validation, 1050 that is iff the mean arrival rate of requests for resource R is 1051 greater than half the change rate of R. 1053 When observing the resource R, M_R is always upper bounded by 2/T_C. 1055 8.3. Use of CoAP Blockwise Transfer 1057 A reverse HC proxy SHOULD support CoAP blockwise transfers 1058 [I-D.ietf-core-block] to allow transport of large CoAP payloads while 1059 avoiding excessive link-layer fragmentation in constrained networks, 1060 and to cope with small datagram buffers in CoAP end-points as 1061 described in [RFC7252] Section 4.6. 1063 A reverse HC proxy SHOULD attempt to retry a payload-carrying CoAP 1064 PUT or POST request with blockwise transfer if the destination CoAP 1065 server responded with 4.13 (Request Entity Too Large) to the original 1066 request. A reverse HC proxy SHOULD attempt to use blockwise transfer 1067 when sending a CoAP PUT or POST request message that is larger than 1068 BLOCKWISE_THRESHOLD bytes. The value of BLOCKWISE_THRESHOLD is 1069 implementation-specific, for example it can be: 1071 o calculated based on a known or typical UDP datagram buffer size 1072 for CoAP end-points, or 1074 o set to N times the known size of a link-layer frame in a 1075 constrained network where e.g. N=5, or 1077 o preset to a known IP MTU value, or 1079 o set to a known Path MTU value. 1081 The value BLOCKWISE_THRESHOLD, or the parameters from which it is 1082 calculated, should be configurable in a proxy implementation. The 1083 maximum block size the proxy will attempt to use in CoAP requests 1084 should also be configurable. 1086 The reverse HC proxy SHOULD detect CoAP end-points not supporting 1087 blockwise transfers. This can be done by checking for a 4.02 (Bad 1088 Option) response returned by an end-point in response to a CoAP 1089 request with a Block* Option, and subsequent absence of the 4.02 in 1090 response to the same request without Block* Options. This allows the 1091 reverse HC proxy to be more efficient, not attempting repeated 1092 blockwise transfers to CoAP servers that do not support it. 1094 8.4. CoAP Multicast 1096 A reverse HC proxy MAY support CoAP multicast. If it does, the 1097 reverse HC proxy sends out a multicast CoAP request if the Target 1098 CoAP URI's authority is a multicast IP literal or resolves to a 1099 multicast IP address; assuming the proper security measures are in 1100 place to mitigate security risks of CoAP multicast (Section 10). If 1101 the security policies do not allow the specific CoAP multicast 1102 request to be made, the reverse HC proxy SHOULD respond 403 1103 (Forbidden). 1105 If a reverse HC proxy does not support CoAP multicast, it SHOULD 1106 respond 403 (Forbidden) to any valid HTTP request that maps to a CoAP 1107 multicast request. 1109 Details related to supporting CoAP multicast are currently out of 1110 scope of this document since in a reverse proxy scenario a HTTP 1111 client typically expects to receive a single response, not multiple. 1112 However, a reverse HC proxy that implements CoAP multicast may 1113 include application-specific functions to aggregate multiple CoAP 1114 responses into a single HTTP response. We suggest using the 1115 "application/http" internet media type (Section 8.3.2 of [RFC7230]) 1116 to enclose a set of one or more HTTP response messages, each 1117 representing the mapping of one CoAP response. 1119 8.5. Timeouts 1121 If the CoAP server takes a long time in responding, the HTTP client 1122 or any other proxy in between may timeout. Further discussion of 1123 timeouts in HTTP is available in Section 6.2.4 of [RFC7230]. 1125 A reverse HC proxy MUST define an internal timeout for each pending 1126 CoAP request, because the CoAP server may silently die before 1127 completing the request. Assuming the Proxy uses confirmable CoAP 1128 requests, such timeout value T SHOULD be at least 1130 T = MAX_RTT + MAX_SERVER_RESPONSE_DELAY 1132 where MAX_RTT is defined in [RFC7252] and MAX_SERVER_RESPONSE_DELAY 1133 is defined in [RFC7390]. 1135 9. IANA Considerations 1137 9.1. New 'core.hc' Resource Type 1139 This document registers a new Resource Type (rt=) Link Target 1140 Attribute, 'core.hc', in the "Resource Type (rt=) Link Target 1141 Attribute Values" subregistry under the "Constrained RESTful 1142 Environments (CoRE) Parameters" registry. 1144 Attribute Value: core.hc 1146 Description: HTTP to CoAP mapping base resource. 1148 Reference: See Section 5.4. 1150 9.2. New 'coap-payload' Internet Media Type 1152 This document defines the "application/coap-payload" media type with 1153 a single parameter "cf". This media type represents any payload that 1154 a CoAP message can carry, having a content format that can be 1155 identified by a CoAP Content-Format parameter (an integer in range 1156 0-65535). The parameter "cf" is the integer defining the CoAP 1157 content format. 1159 Type name: application 1161 Subtype name: coap-payload 1163 Required parameters: 1165 cf - CoAP Content-Format integer in range 0-65535 denoting the 1166 content format of the CoAP payload carried. 1168 Optional parameters: None 1170 Encoding considerations: 1172 The specific CoAP content format encoding considerations for the 1173 selected Content-Format (cf parameter) apply. 1175 Security considerations: 1177 The specific CoAP content format security considerations for the 1178 selected Content-Format (cf parameter) apply. 1180 Interoperability considerations: 1182 Published specification: (this I-D - TBD) 1184 Applications that use this media type: 1186 HTTP-to-CoAP Proxies. 1188 Fragment identifier considerations: N/A 1189 Additional information: 1191 Deprecated alias names for this type: N/A 1193 Magic number(s): N/A 1195 File extension(s): N/A 1197 Macintosh file type code(s): N/A 1199 Person and email address to contact for further information: 1201 Esko Dijk ("esko@ieee.org") 1203 Intended usage: COMMON 1205 Restrictions on usage: 1207 An application (or user) can only use this media type if it has to 1208 represent a CoAP payload of which the specified CoAP Content-Format 1209 is an unrecognized number; such that a proper translation directly to 1210 the equivalent HTTP media type is not possible. 1212 Author: CoRE WG 1214 Change controller: IETF 1216 Provisional registration? (standards tree only): N/A 1218 10. Security Considerations 1220 The security concerns raised in Section 9.2 of [RFC7230] also apply 1221 to the reverse HC proxy scenario. 1223 A reverse proxy deployed at the boundary of a constrained network is 1224 an easy single point of failure for reducing availability. As such, 1225 special care should be taken in designing, developing and operating 1226 it, keeping in mind that, in most cases, it has fewer limitations 1227 than the constrained devices it is serving. 1229 The following sub paragraphs categorize and discuss a set of specific 1230 security issues related to the translation, caching and forwarding 1231 functionality exposed by a reverse HC proxy. 1233 10.1. Traffic Overflow 1235 Due to the typically constrained nature of CoAP nodes, particular 1236 attention should be given to the implementation of traffic reduction 1237 mechanisms (see Section 8.1), because inefficient proxy 1238 implementations can be targeted by unconstrained Internet attackers. 1239 Bandwidth or complexity involved in such attacks is very low. 1241 An amplification attack to the constrained network may be triggered 1242 by a multicast request generated by a single HTTP request which is 1243 mapped to a CoAP multicast resource, as discussed in Section 11.3 of 1244 [RFC7252]. 1246 The risk likelihood of this amplification technique is higher than an 1247 amplification attack carried out by a malicious constrained device 1248 (e.g. ICMPv6 flooding, like Packet Too Big, or Parameter Problem on 1249 a multicast destination [RFC4732]), since it does not require direct 1250 access to the constrained network. 1252 The feasibility of this attack which disrupts availability of the 1253 targeted CoAP server can be limited by access controlling the exposed 1254 multicast resources, so that only known/authorized users can access 1255 such URIs. 1257 10.2. Handling Secured Exchanges 1259 An HTTP request can be sent to the reverse HC proxy over a secured 1260 connection. However, there may not always exist a secure connection 1261 mapping to CoAP. For example, a secure distribution method for 1262 multicast traffic is complex and may not be implemented (see 1263 [RFC7390]). 1265 A reverse HC proxy should implement rules for security context 1266 translations. For example all "https" unicast requests are 1267 translated to "coaps" requests, or "https" requests are translated to 1268 unsecured "coap" requests. Another rule could specify the security 1269 policy and parameters used for DTLS connections. Such rules will 1270 largely depend on the application and network context in which the HC 1271 proxy operates. These rules should be configurable. 1273 It is RECOMMENDED that, by default, accessing a "coaps" URI is only 1274 allowed from a corresponding "https" URI. 1276 By default, a reverse HC proxy SHOULD reject any secured client 1277 request if there is no configured security policy mapping. This 1278 recommendation may be relaxed in case the destination network is 1279 believed to be secured by other means. Assuming that CoAP nodes are 1280 isolated behind a firewall as in the server-side reverse HC proxy 1281 deployment shown in Figure 1, the reverse HC proxy may be configured 1282 to translate the incoming HTTPS request using plain CoAP (NoSec 1283 mode). 1285 10.3. URI Mapping 1287 The following risks related to the URI mapping described in Section 5 1288 and its use by HC proxies have been identified: 1290 DoS attack on the constrained/CoAP network. 1291 Mitigation: by default deny any Target CoAP URI whose authority is 1292 (or maps to) a multicast address. Then explicitly white-list 1293 multicast resources/authorities that are allowed to be de- 1294 referenced. See also Section 8.4. 1296 Leaking information on the constrained/CoAP network resources and 1297 topology. 1298 Mitigation: by default deny any Target CoAP URI (especially 1299 /.well-known/core is a resource to be protected), and then 1300 explicitly white-list resources that are allowed to be seen from 1301 outside. 1303 The internal CoAP Target resource is totally transparent from 1304 outside. 1305 Mitigation: implement a HTTPS-only interface, which makes the 1306 Target CoAP URI totally opaque to a passive attacker. 1308 11. Acknowledgements 1310 An initial version of Table 2 in Section 7 has been provided in 1311 revision -05 of the CoRE CoAP I-D. Special thanks to Peter van der 1312 Stok for countless comments and discussions on this document, that 1313 contributed to its current structure and text. 1315 Thanks to Carsten Bormann, Zach Shelby, Michele Rossi, Nicola Bui, 1316 Michele Zorzi, Klaus Hartke, Cullen Jennings, Kepeng Li, Brian Frank, 1317 Peter Saint-Andre, Kerry Lynn, Linyi Tian, Dorothy Gellert, Francesco 1318 Corazza for helpful comments and discussions that have shaped the 1319 document. 1321 The research leading to these results has received funding from the 1322 European Community's Seventh Framework Programme [FP7/2007-2013] 1323 under grant agreement n.251557. 1325 12. References 1327 12.1. Normative References 1329 [I-D.ietf-core-block] 1330 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 1331 draft-ietf-core-block-16 (work in progress), October 2014. 1333 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1334 Requirement Levels", BCP 14, RFC 2119, March 1997. 1336 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1337 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1338 3986, January 2005. 1340 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1341 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1343 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1344 and D. Orchard, "URI Template", RFC 6570, March 2012. 1346 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1347 Format", RFC 6690, August 2012. 1349 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1350 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 1351 2014. 1353 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1354 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 1356 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1357 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 1359 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1360 (HTTP/1.1): Authentication", RFC 7235, June 2014. 1362 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1363 Application Protocol (CoAP)", RFC 7252, June 2014. 1365 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1366 Application Protocol (CoAP)", RFC 7641, DOI 10.17487/ 1367 RFC7641, September 2015, 1368 . 1370 12.2. Informative References 1372 [I-D.ietf-core-links-json] 1373 Li, K., Rahman, A., and C. Bormann, "Representing CoRE 1374 Formats in JSON and CBOR", draft-ietf-core-links-json-04 1375 (work in progress), November 2015. 1377 [I-D.ietf-core-resource-directory] 1378 Shelby, Z. and C. Bormann, "CoRE Resource Directory", 1379 draft-ietf-core-resource-directory-02 (work in progress), 1380 November 2014. 1382 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1383 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1384 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1386 [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web 1387 Replication and Caching Taxonomy", RFC 3040, January 2001. 1389 [RFC4732] Handley, M., Rescorla, E., and IAB, "Internet Denial-of- 1390 Service Considerations", RFC 4732, December 2006. 1392 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1393 Representation (CBOR)", RFC 7049, October 2013. 1395 [RFC7390] Rahman, A. and E. Dijk, "Group Communication for the 1396 Constrained Application Protocol (CoAP)", RFC 7390, 1397 October 2014. 1399 Appendix A. Change Log 1401 [Note to RFC Editor: Please remove this section before publication.] 1403 Changes from ietf-08 to ietf-09: 1405 o Clean up requirments language as per Klaus' comment. 1407 Changes from ietf-07 to ietf-08: 1409 o Addressed WGLC review comments from Klaus Hartke as per the 1410 correspondence of March 9, 2016 on the CORE WG mailing list. 1412 Changes from ietf-06 to ietf-07: 1414 o Addressed Ticket #384 - Section 5.4.1 describes briefly 1415 (informative) how to discover CoAP resources from an HTTP client. 1417 o Addressed Ticket #378 - For HTTP media type to CoAP content format 1418 mapping and vice versa: a new draft (TBD) may be proposed in CoRE 1419 which describes an approach for automatic updating of the media 1420 type mapping. This was noted in Section 6.1 but is otherwise 1421 outside the scope of this draft. 1423 o Addressed Ticket #377 - Added IANA section that defines a new HTTP 1424 media type "application/coap-payload" and created new Section 6.2 1425 on how to use it. 1427 o Addressed Ticket #376 - Updated Table 2 (and corresponding note 7) 1428 to indicate that a CoAP 4.05 (Method Not Allowed) Response Code 1429 should be mapped to a HTTP 400 (Bad Request). 1431 o Added note to comply to ABNF when translating CoAP diagnostic 1432 payload to reason-phrase in Section 6.5.3. 1434 Changes from ietf-05 to ietf-06: 1436 o Fully restructured the draft, bringing introductory text more to 1437 the front and allocating main sections to each of the key topics; 1438 addressing Ticket #379; 1440 o Addressed Ticket #382, fix of enhanced form URI template 1441 definition of q in Section 5.3.2; 1443 o Addressed Ticket #381, found a mapping 4.01 to 401 Unauthorized in 1444 Section 7; 1446 o Addressed Ticket #380 (Add IANA registration for "core.hc" 1447 Resource Type) in Section 9; 1449 o Addressed Ticket #376 (CoAP 4.05 response can't be translated to 1450 HTTP 405 by HC proxy) in Section 7 by use of empty 'Allow' header; 1452 o Removed details on the pros and cons of HC proxy placement 1453 options; 1455 o Addressed review comments of Carsten Bormann; 1457 o Clarified failure in mapping of HTTP Accept headers (Section 6.3); 1459 o Clarified detection of CoAP servers not supporting blockwise 1460 (Section 8.3); 1462 o Changed CoAP request timeout min value to MAX_RTT + 1463 MAX_SERVER_RESPONSE_DELAY (Section 8.6); 1465 o Added security section item (Section 10.3) related to use of CoAP 1466 blockwise transfers; 1468 o Many editorial improvements. 1470 Changes from ietf-04 to ietf-05: 1472 o Addressed Ticket #366 (Mapping of CoRE Link Format payloads to be 1473 valid in HTTP Domain?) in Section 6.3.3.2 (Content Transcoding - 1474 CORE Link Format); 1476 o Addressed Ticket #375 (Add requirement on mapping of CoAP 1477 diagnostic payload) in Section 6.3.3.3 (Content Transcoding - 1478 Diagnostic Messages); 1480 o Addressed comment from Yusuke (http://www.ietf.org/mail- 1481 archive/web/core/current/msg05491.html) in Section 6.3.3.1 1482 (Content Transcoding - General); 1484 o Various editorial improvements. 1486 Changes from ietf-03 to ietf-04: 1488 o Expanded use case descriptions in Section 4; 1490 o Fixed/enhanced discovery examples in Section 5.4.1; 1492 o Addressed Ticket #365 (Add text on media type conversion by HTTP- 1493 CoAP proxy) in new Section 6.3.1 (Generalized media type mapping) 1494 and new Section 6.3.2 (Content translation); 1496 o Updated HTTPBis WG draft references to recently published RFC 1497 numbers. 1499 o Various editorial improvements. 1501 Changes from ietf-02 to ietf-03: 1503 o Closed Ticket #351 "Add security implications of proposed default 1504 HTTP-CoAP URI mapping"; 1506 o Closed Ticket #363 "Remove CoAP scheme in default HTTP-CoAP URI 1507 mapping"; 1509 o Closed Ticket #364 "Add discovery of HTTP-CoAP mapping 1510 resource(s)". 1512 Changes from ietf-01 to ietf-02: 1514 o Selection of single default URI mapping proposal as proposed to WG 1515 mailing list 2013-10-09. 1517 Changes from ietf-00 to ietf-01: 1519 o Added URI mapping proposals to Section 4 as per the Email 1520 proposals to WG mailing list from Esko. 1522 Authors' Addresses 1524 Angelo P. Castellani 1525 University of Padova 1526 Via Gradenigo 6/B 1527 Padova 35131 1528 Italy 1530 Email: angelo@castellani.net 1532 Salvatore Loreto 1533 Ericsson 1534 Hirsalantie 11 1535 Jorvas 02420 1536 Finland 1538 Email: salvatore.loreto@ericsson.com 1540 Akbar Rahman 1541 InterDigital Communications, LLC 1542 1000 Sherbrooke Street West 1543 Montreal H3A 3G4 1544 Canada 1546 Phone: +1 514 585 0761 1547 Email: Akbar.Rahman@InterDigital.com 1549 Thomas Fossati 1550 Alcatel-Lucent 1551 3 Ely Road 1552 Milton, Cambridge CB24 6DD 1553 UK 1555 Email: thomas.fossati@alcatel-lucent.com 1556 Esko Dijk 1557 Philips Research 1558 High Tech Campus 34 1559 Eindhoven 5656 AE 1560 The Netherlands 1562 Email: esko.dijk@philips.com