idnits 2.17.1 draft-ietf-core-link-format-10.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 (January 13, 2012) is 4480 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) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-08 -- 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 5785 (Obsoleted by RFC 8615) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Z. Shelby 3 Internet-Draft Sensinode 4 Intended status: Standards Track January 13, 2012 5 Expires: July 16, 2012 7 CoRE Link Format 8 draft-ietf-core-link-format-10 10 Abstract 12 This document defines Web Linking using a link format for use by 13 constrained web servers to describe hosted resources, their 14 attributes and other relationships between links. Based on the HTTP 15 Link Header format defined in RFC5988, the CoRE Link Format is 16 carried as a payload and is assigned an Internet media type. A well- 17 known URI is defined as a default entry-point for requesting the 18 links hosted by a server. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on July 16, 2012. 37 Copyright Notice 39 Copyright (c) 2012 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Web Linking in CoRE . . . . . . . . . . . . . . . . . . . 3 56 1.2. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.2.1. Discovery . . . . . . . . . . . . . . . . . . . . . . 4 58 1.2.2. Resource Collections . . . . . . . . . . . . . . . . . 5 59 1.2.3. Resource Directory . . . . . . . . . . . . . . . . . . 5 60 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 61 2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.1. Target and context URIs . . . . . . . . . . . . . . . . . 7 63 2.2. Link relations . . . . . . . . . . . . . . . . . . . . . . 7 64 2.3. Use of anchors . . . . . . . . . . . . . . . . . . . . . . 8 65 3. CoRE link extensions . . . . . . . . . . . . . . . . . . . . . 8 66 3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 8 67 3.2. Interface description 'if' attribute . . . . . . . . . . . 9 68 3.3. Maximum size estimate 'sz' attribute . . . . . . . . . . . 9 69 4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 9 70 4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 10 71 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 74 7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 14 75 7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 14 76 7.3. New link-format Internet media type . . . . . . . . . . . 14 77 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 78 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 79 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 80 10.1. Normative References . . . . . . . . . . . . . . . . . . . 19 81 10.2. Informative References . . . . . . . . . . . . . . . . . . 19 82 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 84 1. Introduction 86 The Constrained RESTful Environments (CoRE) working group aims at 87 realizing the Representational State Transfer (REST) architecture 88 [REST] in a suitable form for the most constrained nodes (e.g. 8-bit 89 microcontrollers with limited memory) and networks (e.g. 6LoWPAN 90 [RFC4944]). CoRE is aimed at Machine-to-Machine (M2M) applications 91 such as smart energy and building automation. 93 The discovery of resources hosted by a constrained server is very 94 important in machine-to-machine applications where there are no 95 humans in the loop and static interfaces result in fragility. The 96 discovery of resources provided by an HTTP [RFC2616] Web Server is 97 typically called Web Discovery and the description of relations 98 between resources is called Web Linking [RFC5988]. In the present 99 document we refer to the discovery of resources hosted by a 100 constrained web server, their attributes and other resource relations 101 as CoRE Resource Discovery. 103 The main function of such a discovery mechanism is to provide 104 Universal Resource Identifiers (URIs, called links) for the resources 105 hosted by the server, complemented by attributes about those 106 resources and possible further link relations. In CoRE this 107 collection of links is carried as a resource of its own (as opposed 108 to HTTP headers delivered with a specific resource). This document 109 specifies a link format for use in CoRE Resource Discovery by 110 extending the HTTP Link Header Format [RFC5988] to describe these 111 link descriptions. The CoRE Link Format is carried as a payload and 112 is assigned an Internet media type. A well-known URI "/.well-known/ 113 core" is defined as a default entry-point for requesting the list of 114 links about resources hosted by a server, and thus performing CoRE 115 Resource Discovery. This specification is applicable for use with 116 CoAP [I-D.ietf-core-coap], HTTP or any other suitable web transfer 117 protocol. The link format can also be saved in file format. 119 1.1. Web Linking in CoRE 121 What is the difference between the CoRE Link Format and [RFC5988]? 122 Technically the CoRE Link Format is a serialization of a typed link 123 as specified in [RFC5988], used to describe relationships between 124 resources, so-called "Web Linking". In this specification Web 125 Linking is extended with specific constrained M2M attributes, links 126 are carried as a message payload rather than in an HTTP Link Header, 127 and a default interface is defined to discover resources hosted by a 128 server. This specification also defines a new relation type "hosts", 129 which indicates that the resource is hosted by the server from which 130 the link document was requested. 132 Why not just use the HTTP Link Header? In HTTP, the Link Header can 133 be used to carry link information about a resource along with an HTTP 134 response. This works well for the typical use case for a web server 135 and browser, where further information about a particular resource is 136 useful after accessing it. In CoRE the main use case for Web Linking 137 is the discovery of which resources a server hosts in the first 138 place. Although some resources may have further links associated 139 with them, this is expected to be an exception. For that reason the 140 CoRE Link Format serialization is carried as a resource 141 representation of a well-known URI. The CoRE Link Format does re-use 142 the format of the HTTP Link Header serialization defined in 143 [RFC5988]. 145 1.2. Use Cases 147 Typical use cases for Web Linking on today's web include e.g. 148 describing the author of a web page, or describing relations between 149 web pages (next chapter, previous chapter etc.). Web Linking can 150 also be applied to M2M applications, where typed links are used to 151 assist a machine client in finding and understanding how to use 152 resources on a server. In this section a few use cases are described 153 for how the CoRE Link Format could be used in M2M applications. For 154 further technical examples see Section 5. As there are a large range 155 of M2M applications, these use cases are purposely generic. This 156 document assumes that different deployments or application domains 157 will define the appropriate REST Interface Descriptions along with 158 Resource Types to make discovery meaningful. 160 1.2.1. Discovery 162 In M2M applications, for example home or building automation, there 163 is a need for local clients and servers to find and interact with 164 each other without human intervention. The CoRE Link Format can be 165 used by servers in such environments to enable Resource Discovery of 166 the resources hosted by the server. 168 Resource Discovery can be performed either unicast or multicast. 169 When a server's IP address is already known, either a priori or 170 resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast 171 discovery is performed in order to locate the entry point to the 172 resource of interest. This is performed using a GET to /.well-known/ 173 core on the server, which returns a payload in the CoRE Link Format. 174 A client would then match the appropriate Resource Type, Interface 175 Description and possible Content-Type [RFC2045] for its application. 176 These attributes may also be included in the query string in order to 177 filter the number of links returned in a response. 179 Multicast resource discovery is useful when a client needs to locate 180 a resource within a limited scope, and that scope supports IP 181 multicast. A GET request to the appropriate multicast address is 182 made for /.well-known/core. In order to limit the number and size or 183 responses, a query string is recommended with the known attributes. 184 Typically a resource would be discovered based on its Resource Type 185 and/or Interface Description, along with possible application 186 specific attributes. 188 1.2.2. Resource Collections 190 RESTful designs of M2M interfaces often make use of collections of 191 resources. For example an index of temperature sensors on a data 192 collection node or a list of alarms on a home security controller. 193 The CoRE Link Format can be used to make it possible to find the 194 entry point to a collection and traverse its members. The entry 195 point of a collection would always be included in /.well-known/core 196 to enable its discovery. The members of the collection can be 197 defined either through the Interface Description of the resource 198 along with a parameter resource for the size of the collection, or by 199 using the link format to describe each resource in the collection. 200 These links could be located under /.well-known/core or hosted for 201 example in the root resource of the collection. 203 1.2.3. Resource Directory 205 In many deployment scenarios, for example constrained networks with 206 sleeping servers, or large M2M deployments with bandwidth limited 207 access networks, it makes sense to deploy resource directory entities 208 which store links to resources stored on other servers. Think of 209 this as a limited search engine for constrained M2M resources. 211 The CoRE Link Format can be used by a server to register resources 212 with a resource directory, or to allow a resource directory to poll 213 for resources. Resource polling uses the same process as unicast or 214 multicast discovery, however usually without filtering. Resource 215 registration can be achieved by having each server POST their 216 resources to /.well-known/core on the resource directory. This in 217 turn adds links to the resource directory under an appropriate 218 resource. These links can then be discovered by any client by a 219 performing a GET on the resource directory using a query string 220 filter. 222 1.3. Terminology 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 226 document are to be interpreted as described in [RFC2119]. 228 This specification requires readers to be familiar with all the terms 229 and concepts that are discussed in [RFC5988]. This specification 230 makes use of the following terminology: 232 Web Linking 233 A framework for indicating the relationships between web 234 resources. 236 Link 237 Also called "typed links" in RFC5988. A link is a typed 238 connection between two resources identified by URIs. Made up of a 239 context URI, a link relation type, a target URI, and optional 240 target attributes. 242 Link Format 243 A particular serialization of typed links. 245 CoRE Link Format 246 A particular serialization of typed links based the HTTP Link 247 Header serialization defined in Section 5 of RFC5988, but carried 248 as a resource representation with a MIME type. 250 Attribute 251 Properly called "Target Attribute" in RFC5988. A set of key/value 252 pairs that describe the link or its target. 254 CoRE Resource Discovery 255 When a client discovers the list of resources hosted by a server, 256 their attributes and other link relations by accessing /.well- 257 known/core. 259 2. Link Format 261 The CoRE Link Format extends the HTTP Link Header format specified in 262 [RFC5988]. The format does not require special XML or binary 263 parsing, is fairly compact, and is extensible - all important 264 characteristics for CoRE. It should be noted that this link format 265 is just one serialization of typed links defined in [RFC5988], others 266 include HTML link, Atom feed links [RFC4287] or HTTP Link Headers. 267 It is expected that resources discovered in the CoRE Link Format may 268 also be made available in alternative formats on the greater 269 Internet. The CoRE Link Format is only expected to be supported in 270 constrained networks and M2M systems. 272 Section 5 of [RFC5988] did not require an Internet media type for the 273 defined link format, as it was defined to be carried in an HTTP 274 header. This specification thus defines the Internet media type 275 "application/link-format" for the CoRE Link Format (see Section 7.3). 276 Whereas the HTTP Link Header format depends on [RFC2616] for its 277 encoding, the CoRE Link Format is encoded as UTF-8 [RFC3629]. A 278 decoder of the format is not expected to (but not prohibited from) 279 validate UTF-8 encoding and doesn't need to perform any UTF-8 280 normalization. UTF-8 data can be compared bit-wise, which allows 281 values to contain UTF-8 data without any added complexity for 282 constrained nodes. 284 The CoRE link format is the [RFC5988] production named "Link", and 285 imports the ABNF description and associated rules in Section 5 of 286 that document. The "Link:" text is omitted as that is part of the 287 HTTP Link Header. Note that the ABNF in the present document is 288 compliant with [RFC5234]. As in [RFC5988], multiple link 289 descriptions are separated by commas. Note that commas can also 290 occur in quoted strings and URIs but do not end a description. 292 2.1. Target and context URIs 294 Each link conveys one target URI as a URI-reference inside angle 295 brackets ("<>"). The context URI of a link (also called base URI in 296 [RFC3986]) conveyed in the CoRE Link Format is by default built from 297 the scheme and authority parts of the target URI. In the absence of 298 this information in the target URI, the context URI is built from the 299 scheme and authority that was used for referencing the resource 300 returning the set of links, replacing the path with an empty path. 301 Thus by default links can be thought of as describing a target 302 resource hosted by the server. Other relations can be expressed by 303 including an anchor parameter (which defines the context URI) along 304 with an explicit relation parameter. This is an important difference 305 to the way the HTTP Link Header format is used, as it is included in 306 the header of an HTTP response for some URI (this URI is by default 307 the context URI). Thus the HTTP Link Header is by default relating 308 the target URI to the URI that was requested. In comparison, the 309 CoRE link format includes one or more links, each describing a 310 resource hosted by a server by default. Other relations can be 311 expressed by using the anchor parameter. See Section 5 of [RFC3986] 312 for a description of how URIs are constructed from URI references. 314 2.2. Link relations 316 Since links in the CoRE Link Format are typically used to describe 317 resources hosted by a server, and thus in the absence of the relation 318 parameter the new relation type "hosts" is assumed (see Section 7.2). 319 The "hosts" relation type indicates that the target URI is a resource 320 hosted by the server given by the base URI, or, if present, the 321 anchor parameter. 323 To express other relations, links can make use of any registered 324 relation by including the relation parameter. To simplify the 325 constrained implementations, the value of a "rel" parameter in this 326 link format SHOULD NOT contain more than one relation type. There 327 may be cases where multiple relation types cannot be avoided, for 328 example when storing a RFC5988 Link header in this link format. The 329 context of a relation can be defined using the anchor parameter. In 330 this way, relations between resources hosted on a server, or between 331 hosted resources and external resources can be expressed. 333 2.3. Use of anchors 335 As per Section 5.2 of [RFC5988] a link description MAY include an 336 "anchor" attribute, in which case the context is the URI included in 337 that attribute. This is used to describe a relationship between two 338 resources. A consuming implementation can however choose to ignore 339 such links. It is not expected that all implementations will be able 340 to derive useful information from explicitly anchored links. 342 3. CoRE link extensions 344 The following CoRE specific target attributes are defined in addition 345 to the ABNF rules in Section 5 of [RFC5988]. These attributes 346 describe information useful in accessing the target link of the 347 relation, and in some cases may be URIs. These URIs MUST be treated 348 as non resolvable identifiers (they are not meant to be retrieved). 349 When attributes are compared, they MUST be compared as strings. 350 Relationships to resources that are meant to be retrieved should be 351 expressed as separate links using the anchor attribute and the 352 appropriate relation type. 354 link-extension = 355 link-extension =/ ( "rt=" quoted-string ) 356 link-extension =/ ( "if=" quoted-string ) 357 link-extension =/ ( "sz=" cardinal ) 358 cardinal = "0" / %x31-39 *DIGIT 360 3.1. Resource type 'rt' attribute 362 The resource type "rt" attribute is an opaque string used to assign a 363 semantically important type to a resource. One can think of this as 364 a noun describing the resource. In the case of a temperature 365 resource this could be e.g. an application-specific semantic type 366 like "OutdoorTemperature", a Universal Resource Name (URN) like 367 "urn:temperature:outdoor" or a URI referencing a specific concept in 368 an ontology like 369 "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple 370 resource type attributes MAY appear in a link. 372 The resource type attribute is not meant to used to assign a human 373 readable name to a resource. The "title" attribute defined in 374 [RFC5988] is meant for that purpose. 376 3.2. Interface description 'if' attribute 378 The Interface Description "if" attribute is an opaque string used to 379 provide a name, URI or URN indicating a specific interface definition 380 used to interact with the target resource. One can think of this as 381 describing verbs usable on a resource. The Interface Description 382 attribute is meant to describe the generic REST interface to interact 383 with a resource or a set of resources. It is expected that an 384 Interface Description will be re-used by different resource types. 385 For example the resource types "OutdoorTemperature", "DewPoint" and 386 "RelHumidity" could all be accessible using the Interface Description 387 "http://www.example.org/myapp.wadl#sensor". 389 The Interface Description could be for example the URI of a Web 390 Application Description Language (WADL) [WADL] definition of the 391 target resource "http://www.example.org/myapp.wadl#sensor", a URN 392 indicating the type of interface to the resource "urn:myapp:sensor", 393 or an application-specific name "Sensor". Multiple Interface 394 Description attributes MAY appear in a link. 396 3.3. Maximum size estimate 'sz' attribute 398 The maximum size estimate attribute "sz" gives an indication of the 399 maximum size of the resource indicated by the target URI. This 400 attribute is not expected to be included for small resources that can 401 comfortably by carried in a single Maximum Transmission Unit (MTU), 402 but SHOULD be included for resources larger than that. The maximum 403 size estimate attribute MUST NOT appear more than once in a link. 405 Note that there is no defined upper limit to the value of the sz 406 attributes. Implementations MUST be prepared to accept large values. 407 One implementation strategy is to convert any value larger than a 408 reasonable size limit for this implementation to a special value 409 "Big", which in further processing would indicate that a size value 410 was given that was so big that it cannot be processed by this 411 implementation. 413 4. Well-known Interface 415 Resource discovery in CoRE is accomplished through the use of a well- 416 known resource URI which returns a list of links about resources 417 hosted by that server and other link relations. Well-known resources 418 have a path component that begins with "/.well-known/" as specified 419 in [RFC5785]. This document defines a new well-known resource for 420 CoRE Resource Discovery "/.well-known/core". 422 A server implementing this specification MUST support this resource 423 on the default port appropriate for the protocol for the purpose of 424 resource discovery. It is however up to the application which links 425 are included and how they are organized. The resource /.well-known/ 426 core is meant to be used to return links to the entry points of 427 resource interfaces on a server. More sophisticated link 428 organization can be achieved by including links to CoRE Link Format 429 resources located elsewhere on the server, for example to achieve an 430 index. In the absence of any links, a zero-length payload is 431 returned. The resource representation of this resource MUST be the 432 CoRE Link Format described in Section 2. 434 The CoRE resource discovery interface supports the following 435 interactions: 437 o Performing a GET on /.well-known/core to the default port returns 438 a set of links available from the server (if any) in the CoRE Link 439 Format. These links might describe resources hosted on that 440 server, on other servers, or express other kinds of link relations 441 as described in Section 2. 443 o Filtering may be performed on any of the link format attributes 444 using a query string as specified in Section 4.1. For example 445 [GET /.well-known/core?rt=TemperatureC] would request resources 446 with the name TemperatureC. A server is not however required to 447 support filtering. 449 o More capable servers such as proxies could support a resource 450 directory by requesting the resource descriptions of other end- 451 points or allowing servers to POST requests to /.well-known/core. 452 The details of such resource directory functionality is however 453 out of scope for this document, and is expected to be specified 454 separately. 456 4.1. Query Filtering 458 A server implementing this document MAY recognize the query part of a 459 resource discovery URI as a filter on the resources to be returned. 460 The query part should conform to the following syntax. Note that 461 this only defines querying for a single parameter at a time. 463 filter-query = resource-param "=" query-pattern 464 resource-param = "uri" / parmname 465 query-pattern = search-token [ "*" ] 466 search-token = *search-char 467 search-char = unreserved / pct-encoded 468 / ":" / "@" ; from pchar 469 / "/" / "?" ; from query 470 / "!" / "$" / "'" / "(" / ")" 471 / "+" / "," / ";" / "=" ; from sub-delims 473 The resource-param "uri" refers to the URI-reference between the "<" 474 and ">" characters of a link. Other resource-param values refer to 475 the link attribute they name. Filtering is performed by comparing 476 the query-pattern against the value of the attribute identified by 477 the resource-param for each link-value in the collection of resources 478 identified by the URI path. 480 If the decoded query-pattern does not end with "*", a link value 481 matches the query only if the value of the attribute or URI-reference 482 denoted by the resource-param is byte-wise identical to the query- 483 pattern. If the decoded query-pattern ends with "*", it is 484 sufficient that the remainder of the query-pattern be a prefix of the 485 value denoted by the resource-param. A query-pattern of "*" matches 486 to an empty string value as well as to any other non-empty string. 487 It is not expected that very constrained nodes support filtering. 488 Implementations not supporting filtering MUST simply ignore the query 489 string and return the whole resource for unicast requests. 491 When using a transfer protocol like the Constrained Application 492 Protocol (CoAP) that supports multicast requests, special care needs 493 to be taken. A multicast request with a query string SHOULD NOT be 494 responded to if filtering is not supported or if the filter does not 495 match (to avoid a needless response storm). The exception is in 496 cases where the IP stack interface is not able to indicate that the 497 source address was multicast. 499 5. Examples 501 A few examples of typical link descriptions in this format follows. 502 Multiple resource descriptions in a representation are separated by 503 commas. Linefeeds never occur in the actual format, but are shown in 504 these examples for readability. Although the following examples use 505 CoAP response codes, the examples are applicable to HTTP as well (the 506 corresponding response code would be 200 OK). 508 This example includes links to two different sensors sharing the same 509 Interface Description. 511 REQ: GET /.well-known/core 513 RES: 2.05 "Content" 514 ;if="sensor", 515 ;if="sensor" 517 Without the linefeeds included for readability, the format actually 518 looks as follows. 520 ;if="sensor",;if="sensor" 522 This example arranges link descriptions hierarchically, with the 523 entry point including a link to a sub-resource containing links about 524 the sensors. 526 REQ: GET /.well-known/core 528 RES: 2.05 "Content" 529 ;rt="index" 531 REQ: GET /sensors 533 RES: 2.05 "Content" 534 ;rt="TemperatureC";if="sensor", 535 ;rt="LightLux";if="sensor" 537 An example query filter may look like: 539 REQ: GET /.well-known/core?rt=LightLux 541 RES: 2.05 "Content" 542 ;rt="LightLux";if="sensor" 544 This example shows the use of an anchor attribute to relate the 545 temperature sensor resource to an external description and to an 546 alternative URL. 548 REQ: GET /.well-known/core 550 RES: 2.05 "Content" 551 ;rt="index";title="Sensor Index", 552 ;rt="TemperatureC";if="sensor", 553 ;rt="LightLux";if="sensor", 554 ;anchor="/sensors/temp" 555 ;rel="describedby", 556 ;anchor="/sensors/temp";rel="alternate" 558 If a client is interested to find relations about a particular 559 resource, it can perform a query on the anchor parameter: 561 REQ: GET /.well-known/core?anchor=/sensors/temp 563 RES: 2.05 "Content" 564 ;anchor="/sensors/temp" 565 ;rel="describedby", 566 ;anchor="/sensors/temp";rel="alternate" 568 The following example shows a large firmware resource with a size 569 attribute. The consumer of this link would use the sz attribute to 570 determine if the resource representation is too large and if block 571 transfer would be required to request it. In this case a client with 572 only a 64 KiB flash might only support a 16-bit integer for storing 573 the sz attribute. Thus a special flag or value should be used to 574 indicate "Big" (larger than 64 KiB). 576 REQ: GET /.well-known/core?rt=firmware 578 RES: 2.05 "Content" 579 ;rt="firmware";sz=262144 581 6. Security Considerations 583 This document needs the same security considerations as described in 584 Section 7 of [RFC5988]. The /.well-known/core resource may be 585 protected e.g. using DTLS when hosted on a CoAP server as per 586 [I-D.ietf-core-coap] Section 10.2. 588 Multicast requests using CoAP for the well-known link-format 589 resources could be used to perform denial of service on a constrained 590 network. A multicast request SHOULD only be accepted if the request 591 is sufficiently authenticated and secured using e.g. IPsec or an 592 appropriate object security mechanism. 594 CoRE link format parsers should be aware that a link description may 595 be cyclical, i.e., contain a link to itself. These cyclical links 596 could be direct or indirect (i.e., through referenced link 597 resources). Care should be taken when parsing link descriptions and 598 accessing cyclical links. 600 7. IANA Considerations 602 7.1. Well-known 'core' URI 604 This memo registers the "core" well-known URI in the Well-Known URI 605 Registry as defined by [RFC5785]. 607 URI suffix: core 609 Change controller: IETF 611 Specification document(s): [[ this document ]] 613 Related information: None 615 7.2. New 'hosts' relation type 617 This memo registers the new "hosts" Web Linking relation type as per 618 [RFC5988]. 620 Relation Name: hosts 622 Description: Refers to a resource hosted by the server indicated by 623 the link context. 625 Reference: [[ this document ]] 627 Notes: This relation is used in CoRE where links are retrieved as a 628 /.well-known/core resource representation, and by default the context 629 of the links is the server at coap://authority from which /.well- 630 known/core was requested. 632 Application Data: None 634 7.3. New link-format Internet media type 636 This memo registers the a new Internet media type for the CoRE link 637 format, application/link-format. 639 Type name: application 641 Subtype name: link-format 643 Required parameters: None 645 Optional parameters: None 647 Encoding considerations: Binary data 649 Security considerations: 651 Multicast requests using CoAP for the well-known link-format 652 resources could be used to perform denial of service on a constrained 653 network. A multicast request SHOULD only be accepted if the request 654 is sufficiently authenticated and secured using e.g. IPsec or an 655 appropriate object security mechanism. 657 CoRE link format parsers should be aware that a link description may 658 be cyclical, i.e., contain a link to itself. These cyclical links 659 could be direct or indirect (i.e., through referenced link 660 resources). Care should be taken when parsing link descriptions and 661 accessing cyclical links. 663 Interoperability considerations: 665 Published specification: [[ this document ]] 667 Applications that use this media type: CoAP server and client 668 implementations for resource discovery and HTTP applications that use 669 the link-format as a payload. 671 Additional information: 673 Magic number(s): 675 File extension(s): *.wlnk 677 Macintosh file type code(s): 679 Intended usage: COMMON 681 Restrictions on usage: None 683 Author: CoRE WG 685 Change controller: IETF 687 8. Acknowledgments 689 Special thanks to Peter Bigot, who has made a considerable number 690 reviews and text contributions that greatly improved the document. 691 In particular, Peter is responsible for the ABNF descriptions and the 692 idea for a new "hosts" relation type. 694 Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions 695 and ideas that led to this draft, and to Carsten Bormann, Martin 696 Thomson, Alexey Melnikov and Peter Saint-Andre for extensive comments 697 and contributions that improved the text. 699 Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido 700 Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey 701 Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, 702 Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed 703 Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn and David Ryan 704 for helpful comments and discussions that have shaped the document. 706 9. Changelog 708 Changes from ietf-09 to ietf-10: 710 o Changed to SHOULD NOT for multiple relation types (#178). 712 o Changed to SHOULD NOT for multicast response repression (#179). 714 o Updated ABNF for queries (#179). 716 o Editorial improvements from WGLC comments. 718 Changes from ietf-08 to ietf-09: 720 o Corrected ABNF and editorial nits. 722 o Elided empty responses to multicast request. 724 Changes from ietf-07 to ietf-08: 726 o IESG submission nits. 728 Changes from ietf-06 to ietf-07: 730 o Moved the Content-type attribute (ct=) to the base CoAP 731 specification. 733 Changes from ietf-05 to ietf-06: 735 o Added improved text about the encoding of the format as UTF-8, 736 but treating it as binary data without normalization. 738 Changes from ietf-04 to ietf-05: 740 o Removed mention of UTF-8 as this is already defined by RFC5988 741 (#158) 743 o Changed encoding considerations to "Binary data" (#157) 745 o Updated ABNF to disallow leading zeros in integers (#159) 747 o Updated examples and reference for coap-06 (#152) 749 o Removed the application/link-format CoAP code registration, now 750 included in the CoAP specification directly (#160) 752 Changes from ietf-03 to ietf-04: 754 o Removed the attribute registry (#145). 756 o Requested a CoAP media type for application/link-format (#144). 758 o Editorial and reference improvements from AD review (#146). 760 o Added a range limitation for ct attribute. 762 o Added security considerations and file extension for 763 application/link-format registration. 765 Changes from ietf-02 to ietf-03: 767 o Removed 'obs' attribute definition, now defined in the CoAP 768 Observation spec (#99). 770 o Changed Resource name (n=) to Resource type (rt=) and d= to if= 771 (#121). 773 o Hierarchical organization of links under /.well-known/core 774 removed (#95). 776 o Bug in Section 3.1 on byte-wise query matching fixed (#91). 778 o Explanatory text added about alternative Web link formats (#92). 780 o Fixed a bug in Section 2.2.4 (#93). 782 o Added use case examples (#89). 784 o Clarified how the CoRE link format is used and how it differs 785 from RFC5988 (#90, #98). 787 o Changed the Interface definition format to quoted-string to 788 match the resource type. 790 o Added an IANA registry for CoRE Link Format attributes (#100). 792 Changes from ietf-01 to ietf-02: 794 o Added references to RFC5988 (#41). 796 o Removed sh and id link-extensions (#42). 798 o Defined the use of UTF-8 (#84). 800 o Changed query filter definition for any parameter (#70). 802 o Added more example, now as a separate section (#43). 804 o Mentioned cyclical links in the security section (#57). 806 o Removed the sh and id attributes, added obs and sz attributes 807 (#42). 809 o Improved the context and relation description wrt RFC5988 and 810 requested a new "hosts" default relation type (#85). 812 Changes from ietf-00 to ietf-01: 814 o Editorial changes to correct references. 816 o Formal definition for filter query string. 818 o Removed URI-reference option from "n" and "id". 820 o Added security text about multicast requests. 822 Changes from shelby-00 to ietf-00: 824 o Fixed the ABNF link-extension definitions (quotes around URIs, 825 integer definition). 827 o Clarified that filtering is optional, and the query string is to 828 be ignored if not supported (and the URL path processed as 829 normally). 831 o Required support of wildcard * processing if filtering is 832 supported. 834 o Removed the assumption of a default content-type. 836 10. References 838 10.1. Normative References 840 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 841 Requirement Levels", BCP 14, RFC 2119, March 1997. 843 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 844 10646", STD 63, RFC 3629, November 2003. 846 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 847 Resource Identifier (URI): Generic Syntax", STD 66, 848 RFC 3986, January 2005. 850 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 851 Specifications: ABNF", STD 68, RFC 5234, January 2008. 853 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 855 10.2. Informative References 857 [I-D.ietf-core-coap] 858 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 859 "Constrained Application Protocol (CoAP)", 860 draft-ietf-core-coap-08 (work in progress), October 2011. 862 [REST] Fielding, R., "Architectural Styles and the Design of 863 Network-based Software Architectures", 2000, . 866 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 867 STD 13, RFC 1034, November 1987. 869 [RFC1035] Mockapetris, P., "Domain names - implementation and 870 specification", STD 13, RFC 1035, November 1987. 872 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 873 Extensions (MIME) Part One: Format of Internet Message 874 Bodies", RFC 2045, November 1996. 876 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 877 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 878 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 880 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 881 Syndication Format", RFC 4287, December 2005. 883 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 884 "Transmission of IPv6 Packets over IEEE 802.15.4 885 Networks", RFC 4944, September 2007. 887 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 888 Uniform Resource Identifiers (URIs)", RFC 5785, 889 April 2010. 891 [WADL] Hadley, M., "Web Application Description Language (WADL)", 892 2009, . 895 Author's Address 897 Zach Shelby 898 Sensinode 899 Kidekuja 2 900 Vuokatti 88600 901 FINLAND 903 Phone: +358407796297 904 Email: zach@sensinode.com