idnits 2.17.1 draft-ietf-core-rd-dns-sd-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 : ---------------------------------------------------------------------------- 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 05, 2018) is 2245 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-02) exists of draft-handrews-json-schema-hyperschema-01 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-13 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE K. Lynn 3 Internet-Draft P. van der Stok 4 Intended status: Standards Track Consultants 5 Expires: September 6, 2018 M. Koster 6 SmartThings 7 C. Amsuess 8 Energy Harvesting Solutions 9 March 05, 2018 11 CoRE Resource Directory: DNS-SD mapping 12 draft-ietf-core-rd-dns-sd-01 14 Abstract 16 Resource and service discovery are complimentary. Resource discovery 17 provides fine-grained detail about the content of a server, while 18 service discovery can provide a scalable method to locate servers in 19 large networks. This document defines a method for mapping between 20 CoRE Link Format attributes and DNS-Based Service Discovery fields to 21 facilitate the use of either method to locate RESTful service 22 interfaces (APIs) in mixed HTTP/CoAP environments. 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 https://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 6, 2018. 41 Copyright Notice 43 Copyright (c) 2018 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 (https://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 . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 3 61 1.3. Resource Directories . . . . . . . . . . . . . . . . . . 4 62 1.4. DNS-Based Service Discovery . . . . . . . . . . . . . . . 4 63 2. New Link-Format Attributes . . . . . . . . . . . . . . . . . 5 64 2.1. Resource Instance attribute "ins" . . . . . . . . . . . . 6 65 2.2. Export attribute "exp" . . . . . . . . . . . . . . . . . 6 66 3. Mapping CoRE Link Attributes to DNS-SD Record Fields . . . . 6 67 3.1. Mapping Resource Instance attribute "ins" to . 6 68 3.2. Mapping Resource Type attribute "rt" to . . 7 69 3.3. Domain mapping . . . . . . . . . . . . . . . . . . . . . 7 70 3.4. TXT Record key=value strings . . . . . . . . . . . . . . 7 71 3.5. Importing resource links into DNS-SD . . . . . . . . . . 8 72 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 4.1. DNS entries . . . . . . . . . . . . . . . . . . . . . . . 9 74 5. IANA considerations . . . . . . . . . . . . . . . . . . . . . 9 75 6. Security considerations . . . . . . . . . . . . . . . . . . . 9 76 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 78 7.2. Informative References . . . . . . . . . . . . . . . . . 10 79 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 11 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 82 1. Introduction 84 The Constrained RESTful Environments (CoRE) working group aims at 85 realizing the REST architecture in a suitable form for the most 86 constrained devices (e.g. 8-bit microcontrollers with limited RAM and 87 ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to- 88 machine (M2M) applications such as smart energy and building 89 automation. The main deliverable of CoRE is the Constrained 90 Application Protocol (CoAP) specification [RFC7252]. 92 Automated discovery of resources hosted by a constrained server is 93 critical in M2M applications where human intervention is minimal and 94 static interfaces result in brittleness. CoRE Resource Discovery is 95 intended to support fine-grained discovery of hosted resources, their 96 attributes, and possibly other resource relations [RFC6690]. 98 In contrast, service discovery generally refers to a coarse-grained 99 resolution of an end-point's IP address, port number, and protocol. 100 This definition may be extended to include multi-function devices, 101 where the result of the discovery process may include a path to a 102 resource representing a RESTful service interface and possibly a 103 reference to a description of the interface such as a JSON Hyper- 104 Schema document [I-D.handrews-json-schema-hyperschema]. 106 Resource and service discovery are complimentary in the case of large 107 networks, where the latter can facilitate scaling. This document 108 defines a mapping between CoRE Link Format attributes and DNS-Based 109 Service Discovery (DNS-SD) [RFC6763] fields that permits discovery of 110 CoAP services by either means. It also addresses the CoRE charter 111 goal to interoperate with DNS-SD. 113 1.1. Terminology 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 117 "OPTIONAL" in this document are to be interpreted as described in 118 [RFC2119]. The term "byte" is used in its now customary sense as a 119 synonym for "octet". 121 This specification requires readers to be familiar with all the terms 122 and concepts that are discussed in {-link} and [RFC6690]. Readers 123 should also be familiar with the terms and concepts discussed in 124 [RFC7252]. To describe the REST interfaces defined in this 125 specification, the URI Template format is used [RFC6570]. 127 This specification also makes use of the terminology of 128 [I-D.ietf-core-resource-directory]. 130 1.2. Resource Discovery 132 The main function of Resource Discovery is to provide Universal 133 Resource Identifiers (URIs, also called "links") for the resources 134 hosted by the server, complemented by attributes about those 135 resources and perhaps additional link relations. In CoRE this 136 collection of links and attributes is itself a resource (as opposed 137 to HTTP headers delivered with a specific resource). 139 [RFC6690] specifies a link format for use in CoRE Resource Discovery 140 by extending the HTTP Link Header Format [RFC8288] to describe these 141 link descriptions. The CoRE Link Format is carried as a payload and 142 is assigned an Internet media type. A well-known URI "/.well-known/ 143 core" is defined as a default entry-point for requesting the list of 144 links about resources hosted by a server, and thus performing CoRE 145 Resource Discovery. 147 Resource Discovery can be performed either via unicast or multicast. 148 When a server's IP address is already known, either a priori or 149 resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast 150 discovery is performed in order to locate a URI for the resource of 151 interest. This is performed using a GET to /.well-known/core on the 152 server, which returns a payload in the CoRE Link Format. A client 153 would then match the appropriate Resource Type, Interface 154 Description, and possible Content-Type [RFC2045] for its application. 155 These attributes may also be included in the query string in order to 156 filter the number of links returned in a response. 158 1.3. Resource Directories 160 In many M2M scenarios, direct discovery of resources is not practical 161 due to sleeping nodes, limited bandwidth, or networks where multicast 162 traffic is inefficient. These problems can be solved by deploying a 163 network element called a Resource Directory (RD), which hosts 164 descriptions of resources held on other servers (referred to as "end- 165 points") and allows lookups to be performed for those resources. An 166 end-point is a web server associated with specific IP address and 167 port; thus a physical device may host one or more end-points. End- 168 points may also act as clients. 170 The Resource Directory implements a set of REST interfaces for end- 171 points to register and maintain sets of Web Links, called resource 172 directory entries. [I-D.ietf-core-resource-directory] specifies the 173 web interfaces that an RD supports in order for web servers to 174 discover the RD and to register, maintain, lookup and remove resource 175 descriptions; for the RD to validate entries; and for clients to 176 lookup resources from the RD. Furthermore, new link attributes 177 useful in conjunction with an RD are defined. 179 1.4. DNS-Based Service Discovery 181 DNS-Based Service Discovery (DNS-SD) defines a conventional method of 182 configuring DNS PTR, SRV, and TXT resource records to facilitate 183 discovery of services (such as CoAP servers in a subdomain) using the 184 existing DNS infrastructure. This section gives a brief overview of 185 DNS-SD; see [RFC6763] for a detailed specification. 187 DNS-SD service names are limited to 255 bytes and are of the form: 189 Service Name = .. 191 The service name is the label of SRV/TXT resource records. The SRV 192 RR specifies the host and the port of the endpoint. The TXT RR 193 provides additional information in the form of key/value pairs. 195 The part of the service name is identical to the global (DNS 196 subdomain) part of the authority in URIs that identify the resources 197 on an individual server or group of servers. 199 The part is composed of at least two labels. The first 200 label of the pair is the application protocol name [RFC6335] preceded 201 by an underscore character. The second label indicates the transport 202 and is always "_udp" for CoAP services. In cases where narrowing the 203 scope of the search may be useful, these labels may be optionally 204 preceded by a subtype name followed by the "_sub" label. An example 205 of this more specific is "lamp._sub._dali._udp". Only 206 the rightmost pair of labels is used in SRV and TXT record names. 208 The default part of the service name may be set at the 209 factory or during the commissioning process. It SHOULD uniquely 210 identify an instance of within a . Taken 211 together, these three elements comprise a unique name for an SRV/ TXT 212 record pair within the DNS subdomain. 214 The granularity of a service name MAY be that of a host or group, or 215 it could represent a particular resource within a CoAP server. The 216 SRV record contains the host name (AAAA record name) and port of the 217 service while protocol is part of the service name. In the case 218 where a service name identifies a particular resource, the path part 219 of the URI must be carried in a corresponding TXT record. 221 A DNS TXT record is in practice limited to a few hundred bytes in 222 length, which is indicated in the resource record header in the DNS 223 response message [RFC6763]. The data consists of one or more strings 224 comprising a key=value pair. By convention, the first pair is 225 txtver= (to support different versions of a service 226 description). An example string is: 228 | 0x08 | t | x | t | v | e | r | = | 1 | 230 2. New Link-Format Attributes 232 When using the CoRE Link Format to describe resources being 233 discovered by or posted to a resource directory service, additional 234 information about those resources is useful. This specification 235 defines the following new attributes for use in the CoRE Link Format 236 [RFC6690]: 238 link-extension = ( "ins" "=" (ptoken | quoted-string) ) 239 ; The token or string is max 63 bytes 240 link-extension = ( "exp" ) 242 2.1. Resource Instance attribute "ins" 244 The Resource Instance "ins" attribute is an identifier for this 245 resource, which makes it possible to distinguish it from other 246 similar resources. This attribute is similar in use to the 247 portion of a DNS-SD record (see Section 1.4, and SHOULD be 248 unique across resources with the same Resource Type attribute in the 249 domain it is used. A Resource Instance might be a descriptive string 250 like "Ceiling Light, Room 3", a short ID like "AF39" or a unique UUID 251 or iNumber. This attribute is used by a Resource Directory to 252 distinguish between multiple instances of the same resource type 253 within the directory. 255 This attribute MUST be no more than 63 bytes in length. The resource 256 identifier attribute MUST NOT appear more than once in a link 257 description. This attribute MAY be used as a query parameter in the 258 RD Lookup Function Set defined in Section 7 of 259 [I-D.ietf-core-resource-directory]. 261 2.2. Export attribute "exp" 263 The Export "exp" attribute is used as a flag to indicate that a link 264 description MAY be exported by a resource directory to external 265 directories. 267 The CoRE Link Format is used for many purposes between CoAP 268 endpoints. Some are useful mainly locally, for example checking the 269 observability of a resource before accessing it, determining the size 270 of a resource, or traversing dynamic resource structures. However, 271 other links are very useful to be exported to other directories, for 272 example the entry point resource to a functional service. This 273 attribute MAY be used as a query parameter in the RD Lookup Function 274 Set defined in Section 7 of [I-D.ietf-core-resource-directory]. 276 3. Mapping CoRE Link Attributes to DNS-SD Record Fields 278 3.1. Mapping Resource Instance attribute "ins" to 280 The Resource Instance "ins" attribute maps to the part of 281 a DNS-SD service name. It is stored directly in the DNS as a single 282 DNS label of canonical precomposed UTF-8 [RFC3629] "Net-Unicode" 283 (Unicode Normalization Form C) [RFC5198] text. However, to the 284 extent that the "ins" attribute may be chosen to match the DNS host 285 name of a service, it SHOULD use the syntax defined in Section 3.5 of 286 [RFC1034] and Section 2.1 of [RFC1123]. 288 The part of the name of a service being offered on the 289 network SHOULD be configurable by the user setting up the service, so 290 that he or she may give it an informative name. However, the device 291 or service SHOULD NOT require the user to configure a name before it 292 can be used. A sensible choice of default name can allow the device 293 or service to be accessed in many cases without any manual 294 configuration at all. The default name should be short and 295 descriptive, and MAY include a collision-resistant substring such as 296 the lower bits of the device's MAC address, serial number, 297 fingerprint, or other identifier in an attempt to make the name 298 relatively unique. 300 DNS labels are currently limited to 63 bytes in length and the entire 301 service name may not exceed 255 bytes. 303 3.2. Mapping Resource Type attribute "rt" to 305 The resource type "rt" attribute is mapped into the 306 part of a DNS-SD service name and SHOULD conform to the reg-rel-type 307 production of the Link Format defined in Section 2 of [RFC6690]. The 308 "rt" attribute MUST be composed of at least a single Net-Unicode text 309 string, without underscore '_' or period '.' and limited to 15 bytes 310 in length, which represents the application protocol name. This 311 string is mapped to the DNS-SD by prepending an 312 underscore and appending a period followed by the "_udp" label. For 313 example, rt="dali" is mapped into "_dali._udp". 315 The application protocol name may be optionally followed by a period 316 and a service subtype name consisting of a Net-Unicode text string, 317 without underscore or period and limited to 63 bytes. This string is 318 mapped to the DNS-SD by appending a period followed by 319 the "_sub" label and then appending a period followed by the service 320 type label pair derived as in the previous paragraph. For example, 321 rt="dali.light" is mapped into "light._sub._dali._udp". 323 The resulting string is used to form labels for DNS-SD records which 324 are stored directly in the DNS. 326 3.3. Domain mapping 328 TBD: A method must be specified to determine in which DNS zone the 329 CoAP service should be registered. See, for example, Section 11 in 330 [RFC6763]. 332 3.4. TXT Record key=value strings 334 A number of [RFC6763] key/value pairs are derived from link-format 335 information, to be exported in the DNS-SD as key=value strings in a 336 TXT record ([RFC6763], Section 6.3). 338 The resource is exported as key/value pair "path=". 340 The Interface Description "if" attribute is exported as key/value 341 pair "if=". 343 The DNS TXT record can be further populated by importing any other 344 resource description attributes as they share the same key=value 345 format specified in Section 6 of [RFC6763]. 347 3.5. Importing resource links into DNS-SD 349 Assuming the ability to query a Resource Directory or multicast a GET 350 (?exp) over the local link, CoAP resource discovery may be used to 351 populate the DNS-SD database in an automated fashion. CoAP resource 352 descriptions (links) can be exported to DNS-SD for exposure to 353 service discovery by using the Resource Instance attribute as the 354 basis for a unique service name, composed with the Resource Type as 355 the , and registered in the correct . The agent 356 responsible for exporting records to the DNS zone file SHOULD be 357 authenticated to the DNS server. The following example, using the 358 example lookup location /rd-lookup, shows an agent discovering a 359 resource to be exported: 361 Req: GET /rd-lookup/res?exp 363 Res: 2.05 Content 364 ; 365 exp;rt="dali.light";ins="Spot"; 366 d="office";ep="node1" 368 The agent subsequently registers the following DNS-SD RRs, assuming a 369 zone name "example.com" prefixed with "office": 371 node1.office.example.com. IN AAAA FDFD::1234 372 _dali._udp.office.example.com IN PTR 373 Spot._dali._udp.office.example.com 374 light._sub._dali._udp.example.com IN PTR 375 Spot._dali._udp.office.example.com 376 Spot._dali._udp.office.example.com IN SRV 0 0 5683 377 node1.office.example.com. 378 Spot._dali._udp.office.example.com IN TXT 379 txtver=1;path=/light/1 381 In the above figure the Service Name is chosen as 382 Spot._dali._udp.office.example.com without the light._sub service 383 prefix. An alternative Service Name would be: 384 Spot.light._sub._dali._udp.office.example.com. 386 4. Examples 388 4.1. DNS entries 390 It may be profitable to discover the light groups for applications, 391 which are unaware ot the existence of the RD. An agent needs to 392 query the RD to return all groups which are exported to be inserted 393 into DNS. 395 Req: GET /rd-lookup/gp?exp 397 Res: 2.05 Content 398 ;exp;gp="grp_R2-4-015;ins="grp1234"; 399 ep="lm_R2-4-015_wndw"; 400 ep="lm_R2-4-015_door 402 The group with FQDN grp_R2-4-015.bc.example.com can be entered into 403 the DNS by the agent. The accompanying instance name is grp1234. 404 The is chosen to be _group._udp. The agent enters the 405 following RRs into the DNS. 407 grp_R2-4-015.bc.example.com. IN AAAA FF05::1 408 _group._udp.bc.example.com IN PTR 409 grp1234._group._udp.bc.example.com 410 grp1234._group._udp.bc.example.com IN SRV 0 0 5683 411 grp_R2-4-015_door.bc.example.com. 412 grp1234._group._udp.bc.example.com IN TXT 413 txtver=1;path=/light/grp1 415 From then on, applications unaware of the existence of the RD can use 416 DNS to access the lighting group. 418 5. IANA considerations 420 TBD 422 6. Security considerations 424 TBD 426 7. References 428 7.1. Normative References 430 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 431 Requirement Levels", BCP 14, RFC 2119, 432 DOI 10.17487/RFC2119, March 1997, 433 . 435 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 436 Cheshire, "Internet Assigned Numbers Authority (IANA) 437 Procedures for the Management of the Service Name and 438 Transport Protocol Port Number Registry", BCP 165, 439 RFC 6335, DOI 10.17487/RFC6335, August 2011, 440 . 442 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 443 and D. Orchard, "URI Template", RFC 6570, 444 DOI 10.17487/RFC6570, March 2012, 445 . 447 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 448 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 449 . 451 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 452 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 453 . 455 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 456 DOI 10.17487/RFC8288, October 2017, 457 . 459 7.2. Informative References 461 [I-D.handrews-json-schema-hyperschema] 462 Andrews, H. and A. Wright, "JSON Hyper-Schema: A 463 Vocabulary for Hypermedia Annotation of JSON", draft- 464 handrews-json-schema-hyperschema-01 (work in progress), 465 January 2018. 467 [I-D.ietf-core-resource-directory] 468 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 469 Amsuess, "CoRE Resource Directory", draft-ietf-core- 470 resource-directory-13 (work in progress), March 2018. 472 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 473 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 474 . 476 [RFC1035] Mockapetris, P., "Domain names - implementation and 477 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 478 November 1987, . 480 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 481 Application and Support", STD 3, RFC 1123, 482 DOI 10.17487/RFC1123, October 1989, 483 . 485 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 486 Extensions (MIME) Part One: Format of Internet Message 487 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 488 . 490 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 491 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 492 2003, . 494 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 495 Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, 496 . 498 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 499 Application Protocol (CoAP)", RFC 7252, 500 DOI 10.17487/RFC7252, June 2014, 501 . 503 Acknowledgements 505 This document was split out from [I-D.ietf-core-resource-directory]. 506 Zach Shelby was a co-author of the original version of this draft. 508 Authors' Addresses 510 Kerry Lynn 511 Consultant 513 Phone: +1 978-460-4253 514 Email: kerlyn@ieee.org 516 Peter van der Stok 517 Consultant 519 Phone: +31 492474673 (Netherlands), +33 966015248 (France) 520 Email: consultancy@vanderstok.org 521 URI: www.vanderstok.org 522 Michael Koster 523 SmartThings 524 665 Clyde Avenue 525 Mountain View 94043 526 USA 528 Phone: +1 707-502-5136 529 Email: Michael.Koster@smartthings.com 531 Christian Amsuess 532 Energy Harvesting Solutions 533 Hollandstr. 12/4 534 1020 535 Austria 537 Phone: +43 664-9790639 538 Email: c.amsuess@energyharvesting.at