idnits 2.17.1 draft-amsuess-core-resource-directory-extensions-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 8 instances of too long lines in the document, the longest one being 21 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 124: '... proxy) MUST come up with a "Proxy U...' RFC 2119 keyword, line 128: '... The Proxy URL SHOULD have no path c...' RFC 2119 keyword, line 133: '... The RD MAY mint several alternative...' RFC 2119 keyword, line 150: '...rminates, the RD SHOULD treat the regi...' RFC 2119 keyword, line 151: '...ifetime has not been exceeded) and MAY...' (14 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 22, 2019) is 1740 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 521 -- Looks like a reference, but probably isn't: '2' on line 523 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-23 == Outdated reference: A later version (-15) exists of draft-tiloca-core-oscore-discovery-03 Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE C. Amsuess 3 Internet-Draft July 22, 2019 4 Intended status: Experimental 5 Expires: January 23, 2020 7 CoRE Resource Directory Extensions 8 draft-amsuess-core-resource-directory-extensions-01 10 Abstract 12 [ See Introduction ] 14 Status of This Memo 16 This Internet-Draft is submitted in full conformance with the 17 provisions of BCP 78 and BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF). Note that other groups may also distribute 21 working documents as Internet-Drafts. The list of current Internet- 22 Drafts is at https://datatracker.ietf.org/drafts/current/. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 This Internet-Draft will expire on January 23, 2020. 31 Copyright Notice 33 Copyright (c) 2019 IETF Trust and the persons identified as the 34 document authors. All rights reserved. 36 This document is subject to BCP 78 and the IETF Trust's Legal 37 Provisions Relating to IETF Documents 38 (https://trustee.ietf.org/license-info) in effect on the date of 39 publication of this document. Please review these documents 40 carefully, as they describe your rights and restrictions with respect 41 to this document. Code Components extracted from this document must 42 include Simplified BSD License text as described in Section 4.e of 43 the Trust Legal Provisions and are provided without warranty as 44 described in the Simplified BSD License. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 49 2. Reverse Proxy requests . . . . . . . . . . . . . . . . . . . 3 50 2.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2.2. Registration . . . . . . . . . . . . . . . . . . . . . . 3 52 2.2.1. Registration updates . . . . . . . . . . . . . . . . 4 53 2.2.2. Proxy behavior . . . . . . . . . . . . . . . . . . . 4 54 2.2.3. On-Demand proxying . . . . . . . . . . . . . . . . . 5 55 2.2.4. Examples . . . . . . . . . . . . . . . . . . . . . . 5 56 2.2.5. Notes on stability and maturity . . . . . . . . . . . 6 57 2.2.6. Security considerations . . . . . . . . . . . . . . . 6 58 3. Infinite lifetime . . . . . . . . . . . . . . . . . . . . . . 7 59 3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 60 4. Lookup across link relations . . . . . . . . . . . . . . . . 7 61 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 5. Lifetime Age . . . . . . . . . . . . . . . . . . . . . . . . 8 63 6. Zone identifier introspection . . . . . . . . . . . . . . . . 8 64 6.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 7. Proxying multicast requests . . . . . . . . . . . . . . . . . 9 66 7.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 69 8.2. Informative References . . . . . . . . . . . . . . . . . 11 70 8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12 71 Appendix A. Change log . . . . . . . . . . . . . . . . . . . . . 12 72 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 12 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 75 1. Introduction 77 This document pools some extensions to the Resource Directory 78 [I-D.ietf-core-resource-directory] that might be useful but have no 79 place in the original document. 81 They might become individual documents for IETF submission, simple 82 registrations in the RD Parameter Registry at IANA, or grow into a 83 shape where they can be submitted as a collection of tools. 85 At its current state, this draft is a collection of ideas. 87 [ This document is being developed at https://gitlab.com/chrysn/ 88 resource-directory-extensions [1]. ] 90 2. Reverse Proxy requests 92 When a registrant registers at a Resource Directory, it might not 93 have a suitable address it can use as a base address. Typical 94 reasons include being inside a NAT without control over port 95 forwarding, or only being able to open outgoing connections (as 96 program running inside a web browser utilizing CoAP over WebSocket 97 [RFC8323] might be). 99 [I-D.ietf-core-resource-directory] suggests (in the Cellular M2M use 100 case) that proxy access to such endpoints can be provided, it gives 101 no concrete mechanism to do that; this is such a mechanism. 103 This mechanism is intended to be a last-resort option to provide 104 connectivity. Where possible, direct connections are preferred. 105 Before registering for proxying, the registrant should attempt to 106 obtain a publicly available port, for example using PCP ([RFC6887]). 108 The same mechanism can also be employed by clients that want to 109 conceal their network address from its clients. 111 2.1. Discovery 113 An RD that provides proxying functionality advertises it by 114 announcing the additional resource type "TBD1" on its directory 115 resource. 117 2.2. Registration 119 A client passes the "proxy=yes" or "proxy=ondemand" query parameter 120 in addition to (but typically instead of) a "base" query parameter. 122 A server that receives a "proxy=yes" query parameter in a 123 registration (or receives "proxy=ondemand" and decides it needs to 124 proxy) MUST come up with a "Proxy URL" on which it accepts requests, 125 and which it uses as a Registration Base URI for lookups on the 126 present registration. 128 The Proxy URL SHOULD have no path component, as acting as a reverse 129 proxy in such a scenario means that any relative references in all 130 representations that are proxied must be recognized and possibly 131 rewritten. 133 The RD MAY mint several alternative Registration Base URIs using 134 different protocols to make the proxied content available; 135 [I-D.silverajan-core-coap-protocol-negotiation] can be used to 136 advertise them. 138 The registrant is not informed of the chosen public name by the RD. 140 This mechanism is applicable to all transports that can be used to 141 register. If proxying is active, the restrictions on when the base 142 parameter needs to be present ([I-D.ietf-core-resource-directory] 143 Registration template) are relaxed: The base parameter may also be 144 absent if the connection originates from an ephemeral port, as long 145 as the underlying protocol supports role reversal, and link-local 146 IPv6 addresses may be used without any concerns of expressibility. 148 If the client uses the role reversal rule relaxation, it keeps that 149 connection open for as long as it wants to be reachable. When the 150 connection terminates, the RD SHOULD treat the registration as having 151 timed out (even if its lifetime has not been exceeded) and MAY 152 eventually remove the registration. 154 2.2.1. Registration updates 156 The "proxy" query parameter can not be changed or repeated in a 157 registration update; RD servers MUST answer 4.00 Bad Request to any 158 registration update that has a "proxy" query parameter. 160 As always, registration updates can explicitly or implicitly update 161 the Registration Base URI. In proxied registrations, those changes 162 are not propagated to lookup, but do change the forwarding address of 163 the proxy. 165 For example, if a registration is established over TCP, an update can 166 come along in a new TCP connection. Starting then, proxied requests 167 are forwarded along that new connection. 169 Note that transports can not be switched in a registration update, as 170 the protocol is part of the registration resource. 172 2.2.2. Proxy behavior 174 The RD operates as a reverse-proxy as described in [RFC7252] 175 Section 5.7.3 at the announced Proxy URL(s), where it decides based 176 on the requested host and port to which registrant endpoint to 177 forward the request. 179 The address the incoming request are forwarded to is the base address 180 of the registration. If an explicit "base" paremter is given, the RD 181 will forward requests to that location. Otherwise, it forwards to 182 the registration's source address (which is the implied base 183 parameter). 185 2.2.3. On-Demand proxying 187 If an endpoint is deployed in an unknown network, it might not know 188 whether it is behind a NAT that would require it to configure an 189 explicit base address, and ask the RD to assist by proxying if 190 necessary by registering with the "proxy=ondemand" query parameter. 192 A server receiving that SHOULD use a different IP address to try to 193 access the registrant's .well-known/core file using a GET request 194 under the Registration Base URI. If that succeeds, it may assume 195 that no NAT is present, and ignore the proxying request. Otherwise, 196 it configures proxying as if "proxy=yes" were requested. 198 Note that this is only a heuristic [ and not tested in deployments 199 yet ]. 201 2.2.4. Examples 203 2.2.4.1. Registration through a firewall 205 Req from [2001:db8:42::9876]:5683: 206 POST coap://rd.example.net/rd?ep=node9876&proxy=ondemand 207 ;rt="example.x" 209 Req from other-address.rd.example.net: 210 GET coap://[2001:db8:42::9876]/.well-known/core 212 Request blocked by stateful firewall around [2001:db8:42::] 214 RD decides that proxying is necessary 216 Res: 2.04 Created 217 Location: /reg/abcd 219 Later, lookup of that registration might say: 221 Req: GET coap://rd.example.net/lookup/res?rt=example.x 223 Res: 2.05 Content 224 ;rt="example.x 226 A request to that resource will end up at an IP address of the RD, 227 which will forward it using its the IP and port on which the 228 registrant had registered as source port, thus reaching the 229 registrant through the stateful firewall. 231 2.2.4.2. Registration from a browser context 233 Req: POST coaps+ws://rd.example.net/rd?ep=node1234&proxy=yes 234 ;rt="core.s" 236 Res: 2.04 Created 237 Location: /reg/123 239 The gyroscope can now not only be looked up in the RD, but also be 240 reached: 242 Req: GET coap://rd.example.net/lookup/res?rt=core.s 244 Res: 2.05 Content 245 ;rt="core.s" 247 In this example, the RD has chosen to do port-based rather than host- 248 based virtual hosting and announces its literal IP address as that 249 allows clients to not send the lengthy Uri-Host option with all 250 requests. 252 2.2.5. Notes on stability and maturity 254 Using this with UDP can be quite fragile; the author only draws on 255 own experience that this can work across cell-phone NATs and does not 256 claim that this will work over generic firewalls. 258 [ It may make sense to have the example as TCP right away. ] 260 2.2.6. Security considerations 262 An RD MAY impose additional restrictions on which endpoints can 263 register for proxying, and thus respond 4.01 Unauthorized to request 264 that would pass had they not requested proxying. 266 Attackers could do third party registrations with an attacked 267 device's address as base URI, though the RD would probably not 268 amplify any attacks in that case. 270 The RD MUST NOT reveal the address at which it reaches the registrant 271 except for adaequately authenticated and authorized debugging 272 purposes, as that address could reveal sensitive location data the 273 registrant may wish to hide by using a proxy. 275 Usual caveats for proxies apply. 277 3. Infinite lifetime 279 An RD can indicate support for infinite lifetimes by adding the 280 resoruce type "TBD2" to its list of resource types. 282 A registrant that wishes to keep its registration alive indefinitely 283 can set the lifetime value as "lt=inf". 285 Registrations with infinite lifetimes never time out. 287 Infinite lifetimes SHOULD only be used by commissioning tools, or for 288 proxy registrations over stateful connections. 290 3.1. Example 292 Had the example of Section 2.2.4.2 discovered support for infinite 293 lifetimes during lookup like this: 295 Req: GET coaps+ws://rd.example.net/.well-known/coer?rt=core.rd* 297 Res: 2.05 Content 298 ;rt="core.rd TBD1 TBD2";ct=40 300 it could register like that: 302 Req: POST coaps+ws://rd.example.net/rd?ep=node1234&proxy=yes<=inf 303 ;rt="core.s" 305 Res: 2.04 Created 306 Location: /reg/123 308 and never need to update the registration for as long as the 309 websocket connection is open. 311 (When it gets terminated, it could try renewing the registration, but 312 needs to be prepared for the RD to already have removed the original 313 registration.) 315 4. Lookup across link relations 317 Resource lookup occasionally needs execute multiple queries to follow 318 links. 320 An RD server (or any other server that supports [RFC6690] compatible 321 lookup), can announce support for following links in resource lookups 322 by announcing support for the TBD3 interface type on its resource 323 lookup. 325 A client can the query that server to not only provide the matched 326 links, but also links that are reachable over relations given in 327 "follow" query parameters. 329 4.1. Example 331 Assume a node presents the following data in its <.well-known/core> 332 resource (and submitted the same to the RD): 334 ;if="core.s";rt="example.temperature", 335 ;rel="calibration-protocol";anchor="/temp", 336 ;rel="describedby";anchor="/temp", 337 ;if="core.s";rt="example.humidity", 338 ;rel="calibration-protocol";anchor="/hum", 340 A lookup client can, in one query, find the temperature sensor and 341 its relevant metadata: 343 Req: GET /rd-lookup/res?rt=example.temperature&follow=calibration-protocol&follow=describedby 345 ;if="core.s";rt="example.temperature";anchor="coap://node1", 346 ;rel="calibration-protocol";anchor="coap://node1/temp", 347 ;rel="describedby";anchor="coap://node1/temp", 349 [ There is a better example [2] in an earlier stage of 350 [I-D.tiloca-core-oscore-discovery] ] 352 [ Given the likelihood of a CoRAL based successor to [RFC6690], this 353 lookup variant might easily be superseeded by a CoRAL FETCH format. 354 ] 356 5. Lifetime Age 358 This extension is described in [I-D.amsuess-core-rd-replication] 359 Section 5.2. 361 The "provenance" extension in Section 5.1 of the same document should 362 probably be expressed differently to avoid using non-target link 363 attributes. 365 6. Zone identifier introspection 367 The 'split-horizon' mechanism introduced in 368 [I-D.ietf-core-resource-directory] (-19) (that registrations with 369 link-local bases can only be read from the zone they registered on) 370 reduces the usability of the endpoint lookup interface for debugging 371 purposes. 373 To allow an administrator to read out the "show-zone-id" query 374 parameter for endpoint and resource lookup is introduced. 376 A Resource Directory that understands this parameter MUST NOT limit 377 lookup results to registrations from the lookup's zone, and MUST use 378 [RFC6874] zone identifiers to annotate which zone those registrations 379 are valid on. 381 The RD MUST limit such requests to authenticated and authorized 382 debugging requests, as registrants may rely on the RD to keep their 383 presence secret from other links. 385 6.1. Example 387 Req: GET /rd-lookup/ep?show-zone-id&et=printer 389 Res: 2.05 Content 390 ;base="coap://[2001:db8::1]";et=printer;ep="bigprinter", 391 ;base="coap://[fe80::99%wlan0]";et=printer;ep="localprinter-1234", 392 ;base="coap://[fe80::99%eth2]";et=printer;ep="localprinter-5678", 394 7. Proxying multicast requests 396 Multicast requests are hard to forward at a proxy: Even if a media 397 type is used in which multiple responses can be aggregated 398 transparently, the proxy can not reliably know when all responses 399 have come in. [RFC7390] Section 2.9 destribes the difficulties in 400 more detail. 402 A proxy MAY expose an interface compatible with the RD lookup 403 interface, which SHOULD be advertised by a link to it that indicates 404 the resource types core.rd-lookup-res and TBD4. 406 The proxy sends multicast requests to All CoAP Nodes ([RFC7252] 407 Section 12.8) requesting their .well-known/core files either eagerly 408 (ie. in regular intervals independent of queries) or on demand (in 409 which case it SHOULD limit the results by applying [RFC6690] query 410 filtering; if it has received multiple query parameters it should 411 forward the one it deems most likely to limit the results, as .well- 412 known/core only supports a single query parameter). 414 In comparison to classical RD operation, this RD behaves roughly as 415 if it had received a simple registration with a All CoAP Nodes 416 address as the source address, if such behavior were specified. The 417 individual registrations that result from this neither have an 418 explicit registration resource nor an explicit endpoint name; given 419 that the endpoint lookup interface is not present on such proxies, 420 neither can be queried. 422 Clients that would intend to do run a multicast discovery operation 423 behind the proxy can then instead query that resource lookup 424 interface. They SHOULD use observation on lookups, as an on-demand 425 implementation MAY return the first result before others have 426 arrived, or MAY even return an empty link set immediately. 428 7.1. Example 430 Req: GET coap+ws://gateway.example.com/.well-known/core?rt=TBD4 432 Res: 2.05 Content 433 ;rt="core.rd-lookup-res TBD4";ct=40 435 Req: GET coap+ws://gateway.example.com/discover?rt=core.s 436 Observe: 0 438 Res: 2.05 Content 439 Observe: 0 440 Content-Format: 40 441 (empty payload) 443 At the same time, the proxy sends out multicast requests on its 444 interfaces: 446 Req: GET coap://ff05::fd/.well-known/core?rt=core.s 448 Res (from [2001:db8::1]:5683): 2.05 Content 449 ;ct="0 112";rt="core.s" 451 Res (from [2001:db8::2]:5683): 2.05 Content 452 ;ct="0 112";rt="core.s" 454 upon receipt of which it sends out a notification to the websocket 455 client: 457 Res: 2.05 Content 458 Observe: 1 459 Content-Format: 40 460 ;ct="0 112";rt="core.s";anchor="coap://[2001:db8::1]", 461 ;ct="0 112";rt="core.s";anchro="coap://[2001:db8::2]" 463 8. References 465 8.1. Normative References 467 [I-D.amsuess-core-rd-replication] 468 Amsuess, C., "Resource Directory Replication", draft- 469 amsuess-core-rd-replication-02 (work in progress), March 470 2019. 472 [I-D.ietf-core-resource-directory] 473 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 474 Amsuess, "CoRE Resource Directory", draft-ietf-core- 475 resource-directory-23 (work in progress), July 2019. 477 [RFC6874] Carpenter, B., Cheshire, S., and R. Hinden, "Representing 478 IPv6 Zone Identifiers in Address Literals and Uniform 479 Resource Identifiers", RFC 6874, DOI 10.17487/RFC6874, 480 February 2013, . 482 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 483 Application Protocol (CoAP)", RFC 7252, 484 DOI 10.17487/RFC7252, June 2014, 485 . 487 8.2. Informative References 489 [I-D.silverajan-core-coap-protocol-negotiation] 490 Silverajan, B. and M. Ocak, "CoAP Protocol Negotiation", 491 draft-silverajan-core-coap-protocol-negotiation-09 (work 492 in progress), July 2018. 494 [I-D.tiloca-core-oscore-discovery] 495 Tiloca, M., Amsuess, C., and P. Stok, "Discovery of OSCORE 496 Groups with the CoRE Resource Directory", draft-tiloca- 497 core-oscore-discovery-03 (work in progress), July 2019. 499 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 500 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 501 . 503 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 504 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 505 DOI 10.17487/RFC6887, April 2013, 506 . 508 [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for 509 the Constrained Application Protocol (CoAP)", RFC 7390, 510 DOI 10.17487/RFC7390, October 2014, 511 . 513 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 514 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 515 Application Protocol) over TCP, TLS, and WebSockets", 516 RFC 8323, DOI 10.17487/RFC8323, February 2018, 517 . 519 8.3. URIs 521 [1] https://gitlab.com/chrysn/resource-directory-extensions 523 [2] https://github.com/ace-wg/ace-oauth/ 524 issues/120#issuecomment-407997786 526 Appendix A. Change log 528 Since -00: 530 o Add multicast proxy usage pattern 532 o ondemand proxying: Probing queries must be sent from a different 533 address 535 o proxying: Point to RFC7252 to describe how the actual proxying 536 happens 538 o proxying: Describe this as a last-resort options and suggest 539 attempting PCP first 541 Appendix B. Acknowledgements 543 [ Reviews from: Jaime Jimenez ] 545 Author's Address 547 Christian Amsuess 548 Hollandstr. 12/4 549 1020 550 Austria 552 Phone: +43-664-9790639 553 Email: christian@amsuess.com