idnits 2.17.1 draft-ietf-core-link-format-12.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 (May 18, 2012) is 4360 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) == Missing Reference: 'RFC5226' is mentioned on line 773, but not defined ** Obsolete undefined reference: RFC 5226 (Obsoleted by RFC 8126) == Missing Reference: 'RFC2026' is mentioned on line 777, but not defined == Unused Reference: 'RFC4288' is defined on line 1014, but no explicit reference was found in the text == Unused Reference: 'RFC5646' is defined on line 1020, but no explicit reference was found in the text == Unused Reference: 'RFC5987' is defined on line 1023, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-09 -- 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: 4 errors (**), 0 flaws (~~), 7 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 May 18, 2012 5 Expires: November 19, 2012 7 CoRE Link Format 8 draft-ietf-core-link-format-12 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 field defined in RFC5988, the CoRE Link Format is carried 16 as a payload and is assigned an Internet media type. A well-known 17 URI is defined as a default entry-point for requesting the links 18 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 November 19, 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 . . . . . . . . . . . . . . . . . 9 63 2.2. Link relations . . . . . . . . . . . . . . . . . . . . . . 9 64 2.3. Use of anchors . . . . . . . . . . . . . . . . . . . . . . 9 65 3. CoRE link attributes . . . . . . . . . . . . . . . . . . . . . 9 66 3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 10 67 3.2. Interface description 'if' attribute . . . . . . . . . . . 10 68 3.3. Maximum size estimate 'sz' attribute . . . . . . . . . . . 10 69 4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 11 70 4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 12 71 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 74 7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 16 75 7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 16 76 7.3. New link-format Internet media type . . . . . . . . . . . 16 77 7.4. Registry for Resource Type and Interface Description 78 Values . . . . . . . . . . . . . . . . . . . . . . . . . . 17 79 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 80 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 19 81 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 82 10.1. Normative References . . . . . . . . . . . . . . . . . . . 23 83 10.2. Informative References . . . . . . . . . . . . . . . . . . 23 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 24 86 1. Introduction 88 The Constrained RESTful Environments (CoRE) working group aims at 89 realizing the Representational State Transfer (REST) architecture 90 [REST] in a suitable form for the most constrained nodes (e.g. 8-bit 91 microcontrollers with limited memory) and networks (e.g. 6LoWPAN 92 [RFC4944]). CoRE is aimed at Machine-to-Machine (M2M) applications 93 such as smart energy and building automation. 95 The discovery of resources hosted by a constrained server is very 96 important in machine-to-machine applications where there are no 97 humans in the loop and static interfaces result in fragility. The 98 discovery of resources provided by an HTTP [RFC2616] Web Server is 99 typically called Web Discovery and the description of relations 100 between resources is called Web Linking [RFC5988]. In the present 101 document we refer to the discovery of resources hosted by a 102 constrained web server, their attributes and other resource relations 103 as CoRE Resource Discovery. 105 The main function of such a discovery mechanism is to provide 106 Universal Resource Identifiers (URIs, called links) for the resources 107 hosted by the server, complemented by attributes about those 108 resources and possible further link relations. In CoRE this 109 collection of links is carried as a resource of its own (as opposed 110 to HTTP headers delivered with a specific resource). This document 111 specifies a link format for use in CoRE Resource Discovery by 112 extending the HTTP Link Header format [RFC5988] to describe these 113 link descriptions. The CoRE Link Format is carried as a payload and 114 is assigned an Internet media type. A well-known relative URI 115 "/.well-known/core" is defined as a default entry-point for 116 requesting the list of links about resources hosted by a server, and 117 thus performing CoRE Resource Discovery. This specification is 118 applicable for use with CoAP [I-D.ietf-core-coap], HTTP or any other 119 suitable web transfer protocol. The link format can also be saved in 120 file format. 122 1.1. Web Linking in CoRE 124 Technically the CoRE Link Format is a serialization of a typed link 125 as specified in [RFC5988], used to describe relationships between 126 resources, so-called "Web Linking". In this specification Web 127 Linking is extended with specific constrained M2M attributes, links 128 are carried as a message payload rather than in an HTTP Link Header 129 field, and a default interface is defined to discover resources 130 hosted by a server. This specification also defines a new relation 131 type "hosts" (from the verb "to host"), which indicates that the 132 resource is hosted by the server from which the link document was 133 requested. 135 In HTTP, the Link Header can be used to carry link information about 136 a resource along with an HTTP response. This works well for the 137 typical use case for a web server and browser, where further 138 information about a particular resource is useful after accessing it. 139 In CoRE the main use case for Web Linking is the discovery of which 140 resources a server hosts in the first place. Although some resources 141 may have further links associated with them, this is expected to be 142 an exception. For that reason the CoRE Link Format serialization is 143 carried as a resource representation of a well-known URI. The CoRE 144 Link Format does re-use the format of the HTTP Link Header 145 serialization defined in [RFC5988]. 147 1.2. Use Cases 149 Typical use cases for Web Linking on today's web include e.g. 150 describing the author of a web page or describing relations between 151 web pages (next chapter, previous chapter etc.). Web Linking can 152 also be applied to M2M applications, where typed links are used to 153 assist a machine client in finding and understanding how to use 154 resources on a server. In this section a few use cases are described 155 for how the CoRE Link Format could be used in M2M applications. For 156 further technical examples see Section 5. As there are a large range 157 of M2M applications, these use cases are purposely generic. This 158 document assumes that different deployments or application domains 159 will define the appropriate REST Interface Descriptions along with 160 Resource Types to make discovery meaningful. 162 1.2.1. Discovery 164 In M2M applications, for example home or building automation, there 165 is a need for local clients and servers to find and interact with 166 each other without human intervention. The CoRE Link Format can be 167 used by servers in such environments to enable Resource Discovery of 168 the resources hosted by the server. 170 Resource Discovery can be performed either unicast or multicast. 171 When a server's IP address is already known, either a priori or 172 resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast 173 discovery is performed in order to locate the entry point to the 174 resource of interest. In this specification, this is performed using 175 a GET to "/.well-known/core" on the server, which returns a payload 176 in the CoRE Link Format. A client would then match the appropriate 177 Resource Type, Interface Description and possible Media type 178 [RFC2045] for its application. These attributes may also be included 179 in the query string in order to filter the number of links returned 180 in a response. 182 Multicast resource discovery is useful when a client needs to locate 183 a resource within a limited scope, and that scope supports IP 184 multicast. A GET request to the appropriate multicast address is 185 made for "/.well-known/core". In order to limit the number and size 186 or responses, a query string is recommended with the known 187 attributes. Typically a resource would be discovered based on its 188 Resource Type and/or Interface Description, along with possible 189 application specific attributes. 191 1.2.2. Resource Collections 193 RESTful designs of M2M interfaces often make use of collections of 194 resources. For example an index of temperature sensors on a data 195 collection node or a list of alarms on a home security controller. 196 The CoRE Link Format can be used to make it possible to find the 197 entry point to a collection and traverse its members. The entry 198 point of a collection would always be included in "/.well-known/core" 199 to enable its discovery. The members of the collection can be 200 defined either through the Interface Description of the resource 201 along with a parameter resource for the size of the collection, or by 202 using the link format to describe each resource in the collection. 203 These links could be located under "/.well-known/core" or hosted for 204 example in the root resource of the collection. 206 1.2.3. Resource Directory 208 In many deployment scenarios, for example constrained networks with 209 sleeping servers, or large M2M deployments with bandwidth limited 210 access networks, it makes sense to deploy resource directory entities 211 which store links to resources stored on other servers. Think of 212 this as a limited search engine for constrained M2M resources. 214 The CoRE Link Format can be used by a server to register resources 215 with a resource directory, or to allow a resource directory to poll 216 for resources. Resource registration can be achieved by having each 217 server POST their resources to "/.well-known/core" on the resource 218 directory. This in turn adds links to the resource directory under 219 an appropriate resource. These links can then be discovered by any 220 client by making a request to a resource directory lookup interface. 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] and [RFC6454]. In 230 addition, this specification 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 on the HTTP Link 247 Header field serialization defined in Section 5 of RFC5988, but 248 carried as a resource representation with a media type. 250 Attribute 251 Properly called "Target Attribute" in RFC5988. A key/value pair 252 that describes 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 field 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 Header 267 fields. It is expected that resources discovered in the CoRE Link 268 Format may also be made available in alternative formats on the 269 greater Internet. The CoRE Link Format is only expected to be 270 supported in 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 field 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 equivalent to the [RFC5988] link format, 285 however the ABNF in the present document is repeated with 286 improvements to be compliant with [RFC5234] and includes new link 287 parameters. As in [RFC5988], multiple link descriptions are 288 separated by commas. Note that commas can also occur in quoted 289 strings and URIs but do not end a description. In order to convert 290 an HTTP Link Header field to this link format, first the "Link:" HTTP 291 header is removed, any LWS is removed, the header value is converted 292 to UTF-8 and any percent-encodings decoded. 294 Link = link-value-list 295 link-value-list = [ link-value *[ "," link-value ]] 296 link-value = "<" URI-Reference ">" *( ";" link-param ) 297 link-param = ( ( "rel" "=" relation-types ) 298 / ( "anchor" "=" <"> URI-Reference <"> ) 299 / ( "rev" "=" relation-types ) 300 / ( "hreflang" "=" Language-Tag ) 301 / ( "media" "=" ( MediaDesc / ( <"> MediaDesc <"> ) ) ) 302 / ( "title" "=" quoted-string ) 303 / ( "title*" "=" ext-value ) 304 / ( "type" "=" ( media-type / quoted-mt ) ) 305 / ( "rt" "=" relation-types ) 306 / ( "if" "=" relation-types ) 307 / ( "sz" "=" cardinal ) 308 / ( link-extension ) ) 309 link-extension = ( parmname [ "=" ( ptoken / quoted-string ) ] ) 310 / ( ext-name-star "=" ext-value ) 311 ext-name-star = parmname "*" ; reserved for RFC2231-profiled 312 ; extensions. Whitespace NOT 313 ; allowed in between. 314 ptoken = 1*ptokenchar 315 ptokenchar = "!" / "#" / "$" / "%" / "&" / "'" / "(" 316 / ")" / "*" / "+" / "-" / "." / "/" / DIGIT 317 / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA 318 / "[" / "]" / "^" / "_" / "`" / "{" / "|" 319 / "}" / "~" 320 media-type = type-name "/" subtype-name 321 quoted-mt = <"> media-type <"> 322 relation-types = relation-type 323 / <"> relation-type *( 1*SP relation-type ) <"> 324 relation-type = reg-rel-type / ext-rel-type 325 reg-rel-type = LOALPHA *( LOALPHA / DIGIT / "." / "-" ) 326 ext-rel-type = URI 327 cardinal = "0" / ( %x31-39 *DIGIT ) 328 LOALPHA = 329 quoted-string = 330 URI = 331 URI-Reference = 332 type-name = 333 subtype-name = 334 MediaDesc = 335 Language-Tag = 336 ext-value = 337 parmname = 339 2.1. Target and context URIs 341 Each link conveys one target URI as a URI-reference inside angle 342 brackets ("<>"). The context URI of a link (also called base URI in 343 [RFC3986]) is determined by the following rules in this 344 specification: 346 (a) The context URI is set to the anchor parameter, when specified, 347 or 349 (b) Origin of the target URI, when specified 351 (c) Origin of the link format document's base URI. 353 2.2. Link relations 355 Since links in the CoRE Link Format are typically used to describe 356 resources hosted by a server, and thus in the absence of the relation 357 parameter the new relation type "hosts" is assumed (see Section 7.2). 358 The "hosts" relation type (from the verb "to host") indicates that 359 the target URI is a resource hosted by the server (i.e. server hosts 360 resource) indicated by the context URI. The target URI MUST be a 361 relative URI of the context URI for this relation type. 363 To express other relations, links can make use of any registered 364 relation by including the relation parameter. The context of a 365 relation can be defined using the anchor parameter. In this way, 366 relations between resources hosted on a server, or between hosted 367 resources and external resources can be expressed. 369 2.3. Use of anchors 371 As per Section 5.2 of [RFC5988] a link description MAY include an 372 "anchor" attribute, in which case the context is the URI included in 373 that attribute. This is used to describe a relationship between two 374 resources. A consuming implementation can however choose to ignore 375 such links. It is not expected that all implementations will be able 376 to derive useful information from explicitly anchored links. 378 3. CoRE link attributes 380 The following CoRE specific target attributes are defined in addition 381 to those already defined in [RFC5988]. These attributes describe 382 information useful in accessing the target link of the relation, and 383 in some cases can use the syntactical form of a URI. Such a URI MAY 384 be dereferenced (for instance to obtain a description of the link 385 relation), but that this is not part of the protocol and MUST NOT be 386 done automatically on link evaluation. When attributes values are 387 compared, they MUST be compared as strings. 389 3.1. Resource type 'rt' attribute 391 The resource type "rt" attribute is an opaque string used to assign 392 an application specific semantic type to a resource. One can think 393 of this as a noun describing the resource. In the case of a 394 temperature resource this could be e.g. an application-specific 395 semantic type like "OutdoorTemperature" or a URI referencing a 396 specific concept in an ontology like 397 "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple 398 resource types MAY be included in the value of this parameter, each 399 separated by a space, similar to the relation attribute. The 400 registry for Resource Type values is defined in Section 7.4. 402 The resource type attribute is not meant to used to assign a human 403 readable name to a resource. The "title" attribute defined in 404 [RFC5988] is meant for that purpose. The resource type attribute 405 MUST NOT appear more than once in a link. 407 3.2. Interface description 'if' attribute 409 The Interface Description "if" attribute is an opaque string used to 410 provide a name or URI indicating a specific interface definition used 411 to interact with the target resource. One can think of this as 412 describing verbs usable on a resource. The Interface Description 413 attribute is meant to describe the generic REST interface to interact 414 with a resource or a set of resources. It is expected that an 415 Interface Description will be re-used by different resource types. 416 For example the resource types "OutdoorTemperature", "DewPoint" and 417 "RelHumidity" could all be accessible using the interface description 418 "http://www.example.org/myapp.wadl#sensor". Multiple interface 419 descriptions MAY be included in the value of this parameter, each 420 separated by a space, similar to the relation attribute. The 421 registry for Interface Description values is defined in Section 7.4. 423 The Interface Description could be for example the URI of a Web 424 Application Description Language (WADL) [WADL] definition of the 425 target resource "http://www.example.org/myapp.wadl#sensor", a URN 426 indicating the type of interface to the resource "urn:myapp:sensor", 427 or an application-specific name "Sensor". The Interface Description 428 attribute MUST NOT appear more than once in a link. 430 3.3. Maximum size estimate 'sz' attribute 432 The maximum size estimate attribute "sz" gives an indication of the 433 maximum size of the resource representation returned by performing a 434 GET on the target URI. For links to CoAP resources this attribute is 435 not expected to be included for small resources that can comfortably 436 be carried in a single Maximum Transmission Unit (MTU), but SHOULD be 437 included for resources larger than that. The maximum size estimate 438 attribute MUST NOT appear more than once in a link. 440 Note that there is no defined upper limit to the value of the sz 441 attributes. Implementations MUST be prepared to accept large values. 442 One implementation strategy is to convert any value larger than a 443 reasonable size limit for this implementation to a special value 444 "Big", which in further processing would indicate that a size value 445 was given that was so big that it cannot be processed by this 446 implementation. 448 4. Well-known Interface 450 Resource discovery in CoRE is accomplished through the use of a well- 451 known resource URI which returns a list of links about resources 452 hosted by that server and other link relations. Well-known resources 453 have a path component that begins with "/.well-known/" as specified 454 in [RFC5785]. This document defines a new well-known resource for 455 CoRE Resource Discovery "/.well-known/core". 457 A server implementing this specification MUST support this resource 458 on the default port appropriate for the protocol for the purpose of 459 resource discovery. It is however up to the application which links 460 are included and how they are organized. The resource "/.well-known/ 461 core" is meant to be used to return links to the entry points of 462 resource interfaces on a server. More sophisticated link 463 organization can be achieved by including links to CoRE Link Format 464 resources located elsewhere on the server, for example to achieve an 465 index. In the absence of any links, a zero-length payload is 466 returned. The resource representation of this resource MUST be the 467 CoRE Link Format described in Section 2. 469 The CoRE resource discovery interface supports the following 470 interactions: 472 o Performing a GET on "/.well-known/core" to the default port 473 returns a set of links available from the server (if any) in the 474 CoRE Link Format. These links might describe resources hosted on 475 that server, on other servers, or express other kinds of link 476 relations as described in Section 2. 478 o Filtering may be performed on any of the link format attributes 479 using a query string as specified in Section 4.1. For example 480 [GET /.well-known/core?rt=TemperatureC] would request resources 481 with the resource type TemperatureC. A server is not however 482 required to support filtering. 484 o More capable servers such as proxies could support a resource 485 directory by requesting the resource descriptions of other end- 486 points or allowing servers to POST requests to "/.well-known/ 487 core". The details of such resource directory functionality is 488 however out of scope for this document, and is expected to be 489 specified separately. 491 4.1. Query Filtering 493 A server implementing this document MAY recognize the query part of a 494 resource discovery URI as a filter on the resources to be returned. 495 The query part should conform to the following syntax. Note that 496 this only defines querying for a single parameter at a time. 498 filter-query = resource-param "=" query-pattern 499 resource-param = "href" / parmname 500 query-pattern = search-token [ "*" ] 501 search-token = *search-char 502 search-char = unreserved / pct-encoded 503 / ":" / "@" ; from pchar 504 / "/" / "?" ; from query 505 / "!" / "$" / "'" / "(" / ")" 506 / "+" / "," / ";" / "=" ; from sub-delims 507 parmname = 508 pct-encoding = 509 unreserved = 511 The resource-param "href" refers to the URI-reference between the "<" 512 and ">" characters of a link. Other resource-param values refer to 513 the link attribute they name. Filtering is performed by comparing 514 the normalized query-pattern (decode percent-encoding and convert to 515 UTF8) against the value of the attribute identified by the resource- 516 param for each link-value in the collection of resources identified 517 by the URI path. 519 If the decoded query-pattern does not end with "*", a link value 520 matches the query only if the value of the attribute or URI-reference 521 denoted by the resource-param is byte-wise identical to the 522 normalized query-pattern. If the decoded query-pattern ends with 523 "*", it is sufficient that the remainder of the query-pattern be a 524 prefix of the value denoted by the resource-param. A query-pattern 525 of "*" matches to an empty string value as well as to any other non- 526 empty string. It is not expected that very constrained nodes support 527 filtering. Implementations not supporting filtering MUST simply 528 ignore the query string and return the whole resource for unicast 529 requests. 531 When using a transfer protocol like the Constrained Application 532 Protocol (CoAP) that supports multicast requests, special care needs 533 to be taken. A multicast request with a query string SHOULD NOT be 534 responded to if filtering is not supported or if the filter does not 535 match (to avoid a needless response storm). The exception is in 536 cases where the IP stack interface is not able to indicate that the 537 destination address was multicast. 539 5. Examples 541 A few examples of typical link descriptions in this format follows. 542 Multiple resource descriptions in a representation are separated by 543 commas. Linefeeds are also included in these examples for 544 readability. Although the following examples use CoAP response 545 codes, the examples are applicable to HTTP as well (the corresponding 546 response code would be 200 OK). 548 This example includes links to two different sensors sharing the same 549 Interface Description. 551 REQ: GET /.well-known/core 553 RES: 2.05 Content 554 ;if="sensor", 555 ;if="sensor" 557 Without the linefeeds inserted here for readability, the format 558 actually looks as follows. 560 ;if="sensor",;if="sensor" 562 This example arranges link descriptions hierarchically, with the 563 entry point including a link to a sub-resource containing links about 564 the sensors. 566 REQ: GET /.well-known/core 568 RES: 2.05 Content 569 ;ct=40 571 REQ: GET /sensors 573 RES: 2.05 "Content" 574 ;rt="TemperatureC";if="sensor", 575 ;rt="LightLux";if="sensor" 577 An example query filter may look like: 579 REQ: GET /.well-known/core?rt=LightLux 581 RES: 2.05 "Content" 582 ;rt="LightLux";if="sensor" 584 This example shows the use of an anchor attribute to relate the 585 temperature sensor resource to an external description and to an 586 alternative URI. 588 REQ: GET /.well-known/core 590 RES: 2.05 "Content" 591 ;ct=40;title="Sensor Index", 592 ;rt="TemperatureC";if="sensor", 593 ;rt="LightLux";if="sensor", 594 ;anchor="/sensors/temp" 595 ;rel="describedby", 596 ;anchor="/sensors/temp";rel="alternate" 598 If a client is interested to find relations about a particular 599 resource, it can perform a query on the anchor parameter: 601 REQ: GET /.well-known/core?anchor=/sensors/temp 603 RES: 2.05 "Content" 604 ;anchor="/sensors/temp" 605 ;rel="describedby", 606 ;anchor="/sensors/temp";rel="alternate" 608 The following example shows a large firmware resource with a size 609 attribute. The consumer of this link would use the sz attribute to 610 determine if the resource representation is too large and if block 611 transfer would be required to request it. In this case a client with 612 only a 64 KiB flash might only support a 16-bit integer for storing 613 the sz attribute. Thus a special flag or value should be used to 614 indicate "Big" (larger than 64 KiB). 616 REQ: GET /.well-known/core?rt=firmware 618 RES: 2.05 "Content" 619 ;rt="firmware";sz=262144 621 6. Security Considerations 623 This document has the same security considerations as described in 624 Section 7 of [RFC5988]. The "/.well-known/core" resource MAY be 625 protected e.g. using DTLS when hosted on a CoAP server as per 626 [I-D.ietf-core-coap] Section 10.2. 628 Some servers might provide resource discovery services to a mix of 629 clients that are trusted to different levels. For example, a 630 lighting control system might allow any client to read state 631 variables, but only certain clients to write state (turn lights on or 632 off). Servers that have authentication and authorization features 633 SHOULD support authentication features of the underlying transport 634 protocols (HTTP or DTLS/TLS) and allow servers to return different 635 lists of links based on a client's identity and authorization. While 636 such servers might not return all links to all requesters, not 637 providing the link does not, by itsef, control access to the relevant 638 resource - a bad actor could know or guess the right URIs. Servers 639 can also lie about the resources available. If it is important for a 640 client to only get information from a known source, then that source 641 needs to be authenticated. 643 Multicast requests using CoAP for the well-known link-format 644 resources could be used to perform denial of service on a constrained 645 network. A multicast request SHOULD only be accepted if the request 646 is sufficiently authenticated and secured using e.g. IPsec or an 647 appropriate object security mechanism. 649 CoRE link format parsers should be aware that a link description may 650 be cyclical, i.e., contain a link to itself. These cyclical links 651 could be direct or indirect (i.e., through referenced link 652 resources). Care should be taken when parsing link descriptions and 653 accessing cyclical links. 655 7. IANA Considerations 657 7.1. Well-known 'core' URI 659 This memo registers the "core" well-known URI in the Well-Known URI 660 Registry as defined by [RFC5785]. 662 URI suffix: core 664 Change controller: IETF 666 Specification document(s): [[ this document ]] 668 Related information: None 670 7.2. New 'hosts' relation type 672 This memo registers the new "hosts" Web Linking relation type as per 673 [RFC5988]. 675 Relation Name: hosts 677 Description: Refers to a resource hosted by the server indicated by 678 the link context. 680 Reference: [[ this document ]] 682 Notes: This relation is used in CoRE where links are retrieved as a 683 "/.well-known/core" resource representation. 685 Application Data: None 687 7.3. New link-format Internet media type 689 This memo registers the a new Internet media type for the CoRE link 690 format, application/link-format. 692 Type name: application 694 Subtype name: link-format 696 Required parameters: None 698 Optional parameters: None 700 Encoding considerations: Binary data (UTF-8) 702 Security considerations: 704 Multicast requests using CoAP for the well-known link-format 705 resources could be used to perform denial of service on a constrained 706 network. A multicast request SHOULD only be accepted if the request 707 is sufficiently authenticated and secured using e.g. IPsec or an 708 appropriate object security mechanism. 710 CoRE link format parsers should be aware that a link description may 711 be cyclical, i.e., contain a link to itself. These cyclical links 712 could be direct or indirect (i.e., through referenced link 713 resources). Care should be taken when parsing link descriptions and 714 accessing cyclical links. 716 Interoperability considerations: 718 Published specification: [[ this document ]] 720 Applications that use this media type: CoAP server and client 721 implementations for resource discovery and HTTP applications that use 722 the link-format as a payload. 724 Additional information: 726 Magic number(s): 728 File extension(s): *.wlnk 730 Macintosh file type code(s): 732 Intended usage: COMMON 734 Restrictions on usage: None 736 Author: CoRE WG 738 Change controller: IETF 740 7.4. Registry for Resource Type and Interface Description Values 742 This specification establishes two new registries, one for Resource 743 Type (rt=) and the other for Interface Description (if=) link target 744 attribute values. This registry is similar to the Link Relation 745 Registry defined in [RFC5988]. No initial entries are defined by 746 this specification for either registry. 748 These registries have the following requirements on values: 750 o Registration values MUST be related to the intended purpose of 751 these attributes as described in Section 3. 753 o Registered values MUST conform to the ABNF reg-rel-type definition 754 of Section 2, meaning the value MUST start with a lower case 755 alphabet character, followed by a sequence of lower case alphabet, 756 numeric, "." or "-" characters. The value MUST NOT contain white 757 space. 759 o It is recommended that the period "." character is used for 760 dividing name segments, and that the dash "-" character is used 761 for making a segment more readable. Example Interface Description 762 values might be "core.batch" and "core.link-batch". 764 o URIs are reserved for free use as extension values for these 765 attributes, and MUST NOT be registered. 767 Values starting with the characters "core" are reserved, and can only 768 be requested for registration when defined in an IETF working group 769 document. 771 Relation types are registered on the advice of a Designated Expert 772 (appointed by the IESG or their delegate), with a Specification 773 Required (using terminology from [RFC5226]). 775 Registration requests consist of the completed registration template 776 below, typically published in an RFC or Open Standard (in the sense 777 described by [RFC2026], Section 7). However, to allow for the 778 allocation of values prior to publication, the Designated Expert may 779 approve registration once they are satisfied that a specification 780 will be published. 782 Note that relation types can be registered by third parties, if the 783 Designated Expert determines that an unregistered relation type is 784 widely deployed and not likely to be registered in a timely manner. 786 The registration template for both registries is: 788 o Attribute Value: 790 o Description: 792 o Reference: 794 o Notes: [optional] 796 Registration requests should be sent to the (TBD)@ietf.org mailing 797 list, marked clearly in the subject line (e.g., "NEW RESOURCE TYPE - 798 example" to register an "example" relation type, or "NEW INTERFACE 799 DESCRIPTION - example" to register an "example" interface 800 description). 802 Within at most 14 days of the request, the Designated Expert(s) will 803 either approve or deny the registration request, communicating this 804 decision to the review list and IANA. Denials should include an 805 explanation and, if applicable, suggestions as to how to make the 806 request successful. 808 Decisions (or lack thereof) made by the Designated Expert can be 809 first appealed to Application Area Directors (contactable using 810 app-ads@tools.ietf.org email address or directly by looking up their 811 email addresses on http://www.iesg.org/ website) and, if the 812 appellant is not satisfied with the response, to the full IESG (using 813 the iesg@iesg.org mailing list). 815 IANA should only accept registry updates from the Designated 816 Expert(s), and should direct all requests for registration to the 817 review mailing list. 819 8. Acknowledgments 821 Special thanks to Peter Bigot, who has made a considerable number 822 reviews and text contributions that greatly improved the document. 823 In particular, Peter is responsible for improving the ABNF 824 descriptions and the idea for a new "hosts" relation type. 826 Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions 827 and ideas that led to this draft, and to Carsten Bormann, Martin 828 Thomson, Alexey Melnikov, Julian Reschke, Joel Halpern, Richard 829 Barnes and Peter Saint-Andre for extensive comments and contributions 830 that improved the text. 832 Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido 833 Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey 834 Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, 835 Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed 836 Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn and David Ryan 837 for helpful comments and discussions that have shaped the document. 839 9. Changelog 841 Changes from ietf-11 to ietf-12: 843 o Changed "uri" to "href" in the filter query (#200) 845 o Upgraded all ABNF to RFC5234 (#197) 846 o Put multiple rt= and if= values in a single attribute (as in 847 rel=) (#199) 849 o Use the Origin definition (#191) 851 o Clarified URI fetching rules (#196) 853 o Added access control and other security consideration 854 improvements (#189) 856 o Fixed normalization for query pattern matching (#192) 858 o Added an anchor restriction for hosts (#193) 860 o New rules for determining link context (#194) 862 o Described how to convert from HTTP Link Header (#190) 864 o Created a registry for rt= and if= values (#195) 866 o Integration of all other IETF LC and IESG comments. 868 Changes from ietf-10 to ietf-11: 870 o Fixed editorial nits. 872 Changes from ietf-09 to ietf-10: 874 o Changed to SHOULD NOT for multiple relation types (#178). 876 o Changed to SHOULD NOT for multicast response repression (#179). 878 o Updated ABNF for queries (#179). 880 o Editorial improvements from WGLC comments. 882 Changes from ietf-08 to ietf-09: 884 o Corrected ABNF and editorial nits. 886 o Elided empty responses to multicast request. 888 Changes from ietf-07 to ietf-08: 890 o IESG submission nits. 892 Changes from ietf-06 to ietf-07: 894 o Moved the Content-type attribute (ct=) to the base CoAP 895 specification. 897 Changes from ietf-05 to ietf-06: 899 o Added improved text about the encoding of the format as UTF-8, 900 but treating it as binary data without normalization. 902 Changes from ietf-04 to ietf-05: 904 o Removed mention of UTF-8 as this is already defined by RFC5988 905 (#158) 907 o Changed encoding considerations to "Binary data" (#157) 909 o Updated ABNF to disallow leading zeros in integers (#159) 911 o Updated examples and reference for coap-06 (#152) 913 o Removed the application/link-format CoAP code registration, now 914 included in the CoAP specification directly (#160) 916 Changes from ietf-03 to ietf-04: 918 o Removed the attribute registry (#145). 920 o Requested a CoAP media type for application/link-format (#144). 922 o Editorial and reference improvements from AD review (#146). 924 o Added a range limitation for ct attribute. 926 o Added security considerations and file extension for 927 application/link-format registration. 929 Changes from ietf-02 to ietf-03: 931 o Removed 'obs' attribute definition, now defined in the CoAP 932 Observation spec (#99). 934 o Changed Resource name (n=) to Resource type (rt=) and d= to if= 935 (#121). 937 o Hierarchical organization of links under /.well-known/core 938 removed (#95). 940 o Bug in Section 3.1 on byte-wise query matching fixed (#91). 942 o Explanatory text added about alternative Web link formats (#92). 944 o Fixed a bug in Section 2.2.4 (#93). 946 o Added use case examples (#89). 948 o Clarified how the CoRE link format is used and how it differs 949 from RFC5988 (#90, #98). 951 o Changed the Interface definition format to quoted-string to 952 match the resource type. 954 o Added an IANA registry for CoRE Link Format attributes (#100). 956 Changes from ietf-01 to ietf-02: 958 o Added references to RFC5988 (#41). 960 o Removed sh and id link-extensions (#42). 962 o Defined the use of UTF-8 (#84). 964 o Changed query filter definition for any parameter (#70). 966 o Added more example, now as a separate section (#43). 968 o Mentioned cyclical links in the security section (#57). 970 o Removed the sh and id attributes, added obs and sz attributes 971 (#42). 973 o Improved the context and relation description wrt RFC5988 and 974 requested a new "hosts" default relation type (#85). 976 Changes from ietf-00 to ietf-01: 978 o Editorial changes to correct references. 980 o Formal definition for filter query string. 982 o Removed URI-reference option from "n" and "id". 984 o Added security text about multicast requests. 986 Changes from shelby-00 to ietf-00: 988 o Fixed the ABNF link-extension definitions (quotes around URIs, 989 integer definition). 991 o Clarified that filtering is optional, and the query string is to 992 be ignored if not supported (and the URI path processed as 993 normally). 995 o Required support of wildcard * processing if filtering is 996 supported. 998 o Removed the assumption of a default content-type. 1000 10. References 1002 10.1. Normative References 1004 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1005 Requirement Levels", BCP 14, RFC 2119, March 1997. 1007 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1008 10646", STD 63, RFC 3629, November 2003. 1010 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1011 Resource Identifier (URI): Generic Syntax", STD 66, 1012 RFC 3986, January 2005. 1014 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 1015 Registration Procedures", BCP 13, RFC 4288, December 2005. 1017 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1018 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1020 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1021 Languages", BCP 47, RFC 5646, September 2009. 1023 [RFC5987] Reschke, J., "Character Set and Language Encoding for 1024 Hypertext Transfer Protocol (HTTP) Header Field 1025 Parameters", RFC 5987, August 2010. 1027 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1029 10.2. Informative References 1031 [I-D.ietf-core-coap] 1032 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 1033 "Constrained Application Protocol (CoAP)", 1034 draft-ietf-core-coap-09 (work in progress), March 2012. 1036 [REST] Fielding, R., "Architectural Styles and the Design of 1037 Network-based Software Architectures", 2000, . 1040 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 1041 STD 13, RFC 1034, November 1987. 1043 [RFC1035] Mockapetris, P., "Domain names - implementation and 1044 specification", STD 13, RFC 1035, November 1987. 1046 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1047 Extensions (MIME) Part One: Format of Internet Message 1048 Bodies", RFC 2045, November 1996. 1050 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1051 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1052 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1054 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1055 Syndication Format", RFC 4287, December 2005. 1057 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 1058 "Transmission of IPv6 Packets over IEEE 802.15.4 1059 Networks", RFC 4944, September 2007. 1061 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1062 Uniform Resource Identifiers (URIs)", RFC 5785, 1063 April 2010. 1065 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1066 December 2011. 1068 [WADL] Hadley, M., "Web Application Description Language (WADL)", 1069 2009, . 1072 Author's Address 1074 Zach Shelby 1075 Sensinode 1076 Kidekuja 2 1077 Vuokatti 88600 1078 FINLAND 1080 Phone: +358407796297 1081 Email: zach@sensinode.com