idnits 2.17.1 draft-ietf-core-link-format-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 16, 2011) is 4516 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 November 16, 2011 5 Expires: May 19, 2012 7 CoRE Link Format 8 draft-ietf-core-link-format-09 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 May 19, 2012. 37 Copyright Notice 39 Copyright (c) 2011 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 . . . . . . . . . . . . . . . . . . . . . 13 74 7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 13 75 7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 14 76 7.3. New link-format Internet media type . . . . . . . . . . . 14 77 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 78 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 79 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 80 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 81 10.2. Informative References . . . . . . . . . . . . . . . . . . 18 82 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19 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. 117 1.1. Web Linking in CoRE 119 What is the difference between the CoRE Link Format and [RFC5988]? 120 Technically the CoRE Link Format is a serialization of a typed link 121 as specified in [RFC5988], used to describe relationships between 122 resources, so-called "Web Linking". In this specification Web 123 Linking is extended with specific constrained M2M attributes, links 124 are carried as a message payload rather than in an HTTP Link Header, 125 and a default interface is defined to discover resources hosted by a 126 server. This specification also defines a new relation type "hosts", 127 which indicates that the resource is hosted by the server from which 128 the link document was requested. 130 Why not just use the HTTP Link Header? In HTTP, the Link Header can 131 be used to carry link information about a resource along with an HTTP 132 response. This works well for the typical use case for a web server 133 and browser, where further information about a particular resource is 134 useful after accessing it. In CoRE the main use case for Web Linking 135 is the discovery of which resources a server hosts in the first 136 place. Although some resources may have further links associated 137 with them, this is expected to be an exception. For that reason the 138 CoRE Link Format serialization is carried as a resource 139 representation of a well-known URI. The CoRE Link Format does re-use 140 the format of the HTTP Link Header serialization defined in 141 [RFC5988]. 143 1.2. Use Cases 145 Typical use cases for Web Linking on today's web include e.g. 146 describing the author of a web page, or describing relations between 147 web pages (next chapter, previous chapter etc.). Web Linking can 148 also be applied to M2M applications, where typed links are used to 149 assist a machine client in finding and understanding how to use 150 resources on a server. In this section a few use cases are described 151 for how the CoRE Link Format could be used in M2M applications. For 152 further technical examples see Section 5. As there are a large range 153 of M2M applications, these use cases are purposely generic. This 154 document assumes that different deployments or application domains 155 will define the appropriate REST interface descriptions along with 156 Resource Types to make discovery meaningful. 158 1.2.1. Discovery 160 In M2M applications, for example home or building automation, there 161 is a need for local clients and servers to find and interact with 162 each other without human intervention. The CoRE Link Format can be 163 used by servers in such environments to enable Resource Discovery of 164 the resources hosted by the server. 166 Resource Discovery can be performed either unicast or multicast. 167 When a server's IP address is already known, either a priori or 168 resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast 169 discovery is performed in order to locate the entry point to the 170 resource of interest. This is performed using a GET to /.well-known/ 171 core on the server, which returns a payload in the CoRE Link Format. 172 A client would then match the appropriate Resource Type, Interface 173 Description and possible Content-Type [RFC2045] for its application. 174 These attributes may also be included in the query string in order to 175 filter the number of links returned in a response. 177 Multicast resource discovery is useful when a client needs to locate 178 a resource within a limited scope, and that scope supports IP 179 multicast. A GET request to the appropriate multicast address is 180 made for /.well-known/core. In order to limit the number and size or 181 responses, a query string is recommended with the known attributes. 182 Typically a resource would be discovered based on its Resource Type 183 and/or Interface Description, along with possible application 184 specific attributes. 186 1.2.2. Resource Collections 188 RESTful designs of M2M interfaces often make use of collections of 189 resources. For example an index of temperature sensors on a data 190 collection node or a list of alarms on a home security controller. 191 The CoRE Link Format can be used to make it possible to find the 192 entry point to a collection and traverse its members. The entry 193 point of a collection would always be included in /.well-known/core 194 to enable its discovery. The members of the collection can be 195 defined either through the interface description of the resource 196 along with a parameter resource for the size of the collection, or by 197 using the link format to describe each resource in the collection. 198 These links could be located under /.well-known/core or hosted for 199 example in the root resource of the collection. 201 1.2.3. Resource Directory 203 In many deployment scenarios, for example constrained networks with 204 sleeping servers, or large M2M deployments with bandwidth limited 205 access networks, it makes sense to deploy resource directory entities 206 which store links to resources stored on other servers. Think of 207 this as a limited search engine for constrained M2M resources. 209 The CoRE Link Format can be used by a server to register resources 210 with a resource directory, or to allow a resource directory to poll 211 for resources. Resource polling uses the same process as unicast or 212 multicast discovery, however usually without filtering. Resource 213 registration can be archived by having each server POST their 214 resources to /.well-known/core on the resource directory. This in 215 turn adds links to the resource directory under an appropriate 216 resource. These links can then be discovered by any client by a 217 performing a GET on the resource directory using a query string 218 filter. 220 1.3. Terminology 222 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 223 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 224 document are to be interpreted as described in [RFC2119]. 226 This specification requires readers to be familiar with all the terms 227 and concepts that are discussed in [RFC5988]. This specification 228 makes use of the following terminology: 230 Web Linking 231 A framework for indicating the relationships between web 232 resources. 234 Link 235 Also called "typed links" in RFC5988. A link is a typed 236 connection between two resources identified by URIs. Made up of a 237 context URI, a link relation type, a target URI, and optional 238 target attributes. 240 Link Format 241 A particular serialization of typed links. 243 CoRE Link Format 244 A particular serialization of typed links based the HTTP Link 245 Header serialization defined in Section 5 of RFC5988, but carried 246 as a resource representation with a MIME type. 248 Attribute 249 Properly called "Target Attribute" in RFC5988. A set of key/value 250 pairs that describe the link or its target. 252 CoRE Resource Discovery 253 When a client discovers the list of resources hosted by a server, 254 their attributes and other link relations by accessing /.well- 255 known/core. 257 2. Link Format 259 The CoRE Link Format extends the HTTP Link Header format specified in 260 [RFC5988]. The format does not require special XML or binary 261 parsing, is fairly compact, and is extensible - all important 262 characteristics for CoRE. It should be noted that this link format 263 is just one serialization of typed links defined in [RFC5988], others 264 include HTML link, Atom feed links [RFC4287] or HTTP Link Headers. 265 It is expected that resources discovered in the CoRE Link Format may 266 also be made available in alternative formats on the greater 267 Internet. The CoRE Link Format is only expected to be supported in 268 constrained networks and M2M systems. 270 Section 5 of [RFC5988] did not require an Internet media type for the 271 defined link format, as it was defined to be carried in an HTTP 272 header. This specification thus defines the Internet media type 273 "application/link-format" for the CoRE Link Format (see Section 7.3). 274 Whereas the HTTP Link Header format depends on [RFC2616] for its 275 encoding, the CoRE Link Format is encoded as UTF-8 [RFC3629]. A 276 decoder of the format is not expected to (but not prohibited from) 277 validate UTF-8 encoding and doesn't need to perform any UTF-8 278 normalization. UTF-8 data can be compared bit-wise, which allows 279 values to contain UTF-8 data without any added complexity for 280 constrained nodes. 282 The CoRE link format is the [RFC5988] production named "Link", and 283 imports the ABNF description and associated rules in Section 5 of 284 that document. The "Link:" text is omitted as that is part of the 285 HTTP Link Header. Note that the ABNF in the present document is 286 compliant with [RFC5234]. As in [RFC5988], multiple link 287 descriptions are separated by commas. Note that commas can also 288 occur in quoted strings and URIs but do not end a description. 290 2.1. Target and context URIs 292 Each link conveys one target URI as a URI-reference inside angle 293 brackets ("<>"). The context URI of a link (also called base URI in 294 [RFC3986]) conveyed in the CoRE Link Format is by default built from 295 the scheme and authority parts of the target URI. In the absence of 296 this information in the target URI, the context URI is built from the 297 scheme and authority that was used for referencing the resource 298 returning the set of links, replacing the path with an empty path. 299 Thus by default links can be thought of as describing a target 300 resource hosted by the server. Other relations can be expressed by 301 including an anchor parameter (which defines the context URI) along 302 with an explicit relation parameter. This is an important difference 303 to the way the HTTP Link Header format is used, as it is included in 304 the header of an HTTP response for some URI (this URI is by default 305 the context URI). Thus the HTTP Link Header is by default relating 306 the target URI to the URI that was requested. In comparison, the 307 CoRE link format includes one or more links, each describing a 308 resource hosted by a server by default. Other relations can be 309 expressed by using the anchor parameter. See Section 5 of [RFC3986] 310 for a description of how URIs are constructed from URI references. 312 2.2. Link relations 314 Since links in the CoRE Link Format are typically used to describe 315 resources hosted by a server, and thus in the absence of the relation 316 parameter the new relation type "hosts" is assumed (see Section 7.2). 317 The "hosts" relation type indicates that the target URI is a resource 318 hosted by the server given by the base URI, or, if present, the 319 anchor parameter. 321 To express other relations a links can make use of any registered 322 relation parameter or target attributes by including the relation 323 parameter. The context of a relation can be defined using the anchor 324 parameter. In this way, relations between resources hosted on a 325 server, or between hosted resources and external resources can be 326 expressed. 328 2.3. Use of anchors 330 As per Section 5.2 of [RFC5988] a link description MAY include an 331 "anchor" attribute, in which case the context is the URI included in 332 that attribute. This is used to describe a relationship between two 333 resources. A consuming implementation can however choose to ignore 334 such links. It is not expected that all implementations will be able 335 to derive useful information from explicitly anchored links. 337 3. CoRE link extensions 339 The following CoRE specific target attributes are defined in addition 340 to the ABNF rules in Section 5 of [RFC5988]. These attributes 341 describe information useful in accessing the target link of the 342 relation, and in some cases may be URIs. These URIs MUST be treated 343 as non resolvable identifiers (they are not meant to be retrieved). 344 When attributes are compared, they MUST be compared as strings. 345 Relationships to resources that are meant to be retrieved should be 346 expressed as separate links using the anchor attribute and the 347 appropriate relation type. 349 link-extension = 350 link-extension =/ ( "rt=" quoted-string ) 351 link-extension =/ ( "if=" quoted-string ) 352 link-extension =/ ( "sz=" cardinal ) 353 cardinal = "0" / %x31-39 *DIGIT 355 3.1. Resource type 'rt' attribute 357 The resource type "rt" attribute is an opaque string used to assign a 358 semantically important type to a resource. One can think of this as 359 a noun describing the resource. In the case of a temperature 360 resource this could be e.g. an application-specific semantic type 361 like "OutdoorTemperature", a Universal Resource Name (URN) like 362 "urn:temperature:outdoor" or a URI referencing a specific concept in 363 an ontology like 364 "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple 365 resource type attributes MAY appear in a link. 367 The resource type attribute is not meant to used to assign a human 368 readable name to a resource. The "title" attribute defined in 370 [RFC5988] is meant for that purpose. 372 3.2. Interface description 'if' attribute 374 The interface description "if" attribute is an opaque string used to 375 provide a name, URI or URN indicating a specific interface definition 376 used to interact with the target resource. One can think of this as 377 describing verbs usable on a resource. The interface description 378 attribute is meant to describe the generic REST interface to interact 379 with a resource or a set of resources. It is expected that an 380 interface description will be re-used by different resource types. 381 For example the resource types "OutdoorTemperature", "DewPoint" and 382 "RelHumidity" could all be accessible using the interface description 383 "http://www.example.org/myapp.wadl#sensor". 385 The interface description could be for example the URI of a Web 386 Application Description Language (WADL) [WADL] definition of the 387 target resource "http://www.example.org/myapp.wadl#sensor", a URN 388 indicating the type of interface to the resource "urn:myapp:sensor", 389 or an application-specific name "Sensor". Multiple interface 390 description attributes MAY appear in a link. 392 3.3. Maximum size estimate 'sz' attribute 394 The maximum size estimate attribute "sz" gives an indication of the 395 maximum size of the resource indicated by the target URI. This 396 attribute is not expected to be included for small resources that can 397 comfortably by carried in a single Maximum Transmission Unit (MTU), 398 but SHOULD be included for resources larger than that. The maximum 399 size estimate attribute MUST NOT appear more than once in a link. 401 Note that there is no defined upper limit to the value of the sz 402 attributes. Implementations MUST be prepared to accept large values. 403 One implementation strategy is to convert any value larger than a 404 reasonable size limit for this implementation to a special value 405 "Big", which in further processing would indicate that a size value 406 was given that was so big that it cannot be processed by this 407 implementation. 409 4. Well-known Interface 411 Resource discovery in CoRE is accomplished through the use of a well- 412 known resource URI which returns a list of links about resources 413 hosted by that server and other link relations. Well-known resources 414 have a path component that begins with "/.well-known/" as specified 415 in [RFC5785]. This document defines a new well-known resource for 416 CoRE Resource Discovery "/.well-known/core". 418 A server implementing this specification MUST support this resource 419 on the default port appropriate for the protocol for the purpose of 420 resource discovery. It is however up to the application which links 421 are included and how they are organized. The resource /.well-known/ 422 core is meant to be used to return links to the entry points of 423 resource interfaces on a server. More sophisticated link 424 organization can be achieved by including links to CoRE Link Format 425 resources located elsewhere on the server, for example to achieve an 426 index. In the absence of any links, a zero-length payload is 427 returned. The resource representation of this resource MUST be the 428 CoRE Link Format described in Section 2. 430 The CoRE resource discovery interface supports the following 431 interactions: 433 o Performing a GET on /.well-known/core to the default port returns 434 a set of links available from the server (if any) in the CoRE Link 435 Format. These links might describe resources hosted on that 436 server, on other servers, or express other kinds of link relations 437 as described in Section 2. 439 o Filtering may be performed on any of the link format attributes 440 using a query string as specified in Section 4.1. For example 441 [GET /.well-known/core?rt=TemperatureC] would request resources 442 with the name TemperatureC. A server is not however required to 443 support filtering. 445 o More capable servers such as proxies could support a resource 446 directory by requesting the resource descriptions of other end- 447 points or allowing servers to POST requests to /.well-known/core. 448 The details of such resource directory functionality is however 449 out of scope for this document, and is expected to be specified 450 separately. 452 4.1. Query Filtering 454 A server implementing this document MAY recognize the query part of a 455 resource discovery URI as a filter on the resources to be returned. 456 The query part should conform to the following syntax. Note that 457 this only defines querying for a single parameter at a time. 459 filter-query = resource-param "=" query-pattern 460 resource-param = "uri" / parmname 461 query-pattern = ptoken [ "*" ] 462 ptoken = 464 The resource-param "uri" refers to the URI-reference between the "<" 465 and ">" characters of a link. Other resource-param values refer to 466 the link attribute they name. Filtering is performed by comparing 467 the query-pattern against the value of the attribute identified by 468 the resource-param for each link-value in the collection of resources 469 identified by the URI path. 471 If the decoded query-pattern does not end with "*", a link value 472 matches the query only if the value of the attribute or URI-reference 473 denoted by the resource-param is bytewise identical to the query- 474 pattern. If the decoded query-pattern ends with "*", it is 475 sufficient that the remainder of the query-pattern be a prefix of the 476 value denoted by the resource-param. A query-pattern of "*" will 477 match that resource-param with an empty string value. It is not 478 expected that very constrained nodes support filtering. 479 Implementations not supporting filtering MUST simply ignore the query 480 string and return the whole resource for unicast requests. 482 When using a transfer protocol like the Constrained Application 483 Protocol (CoAP) that supports multicast requests, special care is 484 taken. A multicast request with a query string MUST NOT be responded 485 to if filtering is not supported or if the filter does not match (to 486 avoid a needless response storm). 488 5. Examples 490 A few examples of typical link descriptions in this format follows. 491 Multiple resource descriptions in a representation are separated by 492 commas. Linefeeds never occur in the actual format, but are shown in 493 these examples for readability. Although the following examples use 494 CoAP response codes, the examples are applicable to HTTP as well (the 495 corresponding response code would be 200 OK). 497 This example includes links to two different sensors sharing the same 498 interface description. 500 REQ: GET /.well-known/core 502 RES: 2.05 "Content" 503 ;rt="TemperatureC";if="sensor", 504 ;rt="LightLux";if="sensor" 506 Without the linefeeds included for readability, the format actually 507 looks as follows. 509 ;rt="TemperatureC";if="sensor", 510 ;rt="LightLux";if="sensor" 511 This example arranges link descriptions hierarchically, with the 512 entry point including a link to a sub-resource containing links about 513 the sensors. 515 REQ: GET /.well-known/core 517 RES: 2.05 "Content" 518 ;rt="index" 520 REQ: GET /sensors 522 RES: 2.05 "Content" 523 ;rt="TemperatureC";if="sensor", 524 ;rt="LightLux";if="sensor" 526 An example query filter may look like: 528 REQ: GET /.well-known/core?rt=LightLux 530 RES: 2.05 "Content" 531 ;rt="LightLux";if="sensor" 533 This example shows the use of an anchor attribute to relate the 534 temperature sensor resource to an external description and to an 535 alternative URL. 537 REQ: GET /.well-known/core 539 RES: 2.05 "Content" 540 ;rt="index";title="Sensor Index", 541 ;rt="TemperatureC";if="sensor", 542 ;rt="LightLux";if="sensor", 543 ;anchor="/sensors/temp" 544 ;rel="describedby", 545 ;anchor="/sensors/temp";rel="alternate" 547 If a client is interested to find relations about a particular 548 resource, it can perform a query on the anchor parameter: 550 REQ: GET /.well-known/core?anchor=/sensors/temp 552 RES: 2.05 "Content" 553 ;anchor="/sensors/temp" 554 ;rel="describedby", 555 ;anchor="/sensors/temp";rel="alternate" 556 The following example shows a large firmware resource with a size 557 attribute. The consumer of this link would use the sz attribute to 558 determine if the resource representation is too large and if block 559 transfer would be required to request it. In this case a client with 560 only a 64 KiB flash might only support a 16-bit integer for storing 561 the sz attribute. Thus a special flag or value should be used to 562 indicate "Big" (larger than 64 KiB). 564 REQ: GET /.well-known/core?rt=firmware 566 RES: 2.05 "Content" 567 ;rt="firmware";sz=262144 569 6. Security Considerations 571 This document needs the same security considerations as described in 572 Section 7 of [RFC5988]. The /.well-known/core resource may be 573 protected e.g. using DTLS when hosted on a CoAP server as per 574 [I-D.ietf-core-coap] Section 10.2. 576 Multicast requests using CoAP for the well-known link-format 577 resources could be used to perform denial of service on a constrained 578 network. A multicast request SHOULD only be accepted if the request 579 is sufficiently authenticated and secured using e.g. IPsec or an 580 appropriate object security mechanism. 582 CoRE link format parsers should be aware that a link description may 583 be cyclical, i.e., contain a link to itself. These cyclical links 584 could be direct or indirect (i.e., through referenced link 585 resources). Care should be taken when parsing link descriptions and 586 accessing cyclical links. 588 7. IANA Considerations 590 7.1. Well-known 'core' URI 592 This memo registers the "core" well-known URI in the Well-Known URI 593 Registry as defined by [RFC5785]. 595 URI suffix: core 597 Change controller: IETF 599 Specification document(s): [[ this document ]] 600 Related information: None 602 7.2. New 'hosts' relation type 604 This memo registers the new "hosts" Web Linking relation type as per 605 [RFC5988]. 607 Relation Name: hosts 609 Description: Refers to a resource hosted by the server indicated by 610 the link context. 612 Reference: [[ this document ]] 614 Notes: This relation is used in CoRE where links are retrieved as a 615 /.well-known/core resource representation, and by default the context 616 of the links is the server at coap://authority from which /.well- 617 known/core was requested. 619 Application Data: None 621 7.3. New link-format Internet media type 623 This memo registers the a new Internet media type for the CoRE link 624 format, application/link-format. 626 Type name: application 628 Subtype name: link-format 630 Required parameters: None 632 Optional parameters: None 634 Encoding considerations: Binary data 636 Security considerations: 638 Multicast requests using CoAP for the well-known link-format 639 resources could be used to perform denial of service on a constrained 640 network. A multicast request SHOULD only be accepted if the request 641 is sufficiently authenticated and secured using e.g. IPsec or an 642 appropriate object security mechanism. 644 CoRE link format parsers should be aware that a link description may 645 be cyclical, i.e., contain a link to itself. These cyclical links 646 could be direct or indirect (i.e., through referenced link 647 resources). Care should be taken when parsing link descriptions and 648 accessing cyclical links. 650 Interoperability considerations: 652 Published specification: [[ this document ]] 654 Applications that use this media type: CoAP server and client 655 implementations for resource discovery and HTTP applications that use 656 the link-format as a payload. 658 Additional information: 660 Magic number(s): 662 File extension(s): *.wlnk 664 Macintosh file type code(s): 666 Intended usage: COMMON 668 Restrictions on usage: None 670 Author: CoRE WG 672 Change controller: IETF 674 8. Acknowledgments 676 Special thanks to Peter Bigot, who has made a considerable number 677 reviews and text contributions that greatly improved the document. 678 In particular, Peter is responsible for the ABNF descriptions and the 679 idea for a new "hosts" relation type. 681 Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions 682 and ideas that led to this draft, and to Carsten Bormann, Martin 683 Thomson, Alexey Melnikov and Peter Saint-Andre for extensive comments 684 and contributions that improved the text. 686 Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido 687 Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey 688 Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, 689 Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed 690 Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn and David Ryan 691 for helpful comments and discussions that have shaped the document. 693 9. Changelog 695 Changes from ietf-08 to ietf-09: 697 o Corrected ABNF and editorial nits. 699 o Elided empty responses to multicast request. 701 Changes from ietf-07 to ietf-08: 703 o IESG submission nits. 705 Changes from ietf-06 to ietf-07: 707 o Moved the Content-type attribute (ct=) to the base CoAP 708 specification. 710 Changes from ietf-05 to ietf-06: 712 o Added improved text about the encoding of the format as UTF-8, 713 but treating it as binary data without normalization. 715 Changes from ietf-04 to ietf-05: 717 o Removed mention of UTF-8 as this is already defined by RFC5988 718 (#158) 720 o Changed encoding considerations to "Binary data" (#157) 722 o Updated ABNF to disallow leading zeros in integers (#159) 724 o Updated examples and reference for coap-06 (#152) 726 o Removed the application/link-format CoAP code registration, now 727 included in the CoAP specification directly (#160) 729 Changes from ietf-03 to ietf-04: 731 o Removed the attribute registry (#145). 733 o Requested a CoAP media type for application/link-format (#144). 735 o Editorial and reference improvements from AD review (#146). 737 o Added a range limitation for ct attribute. 739 o Added security considerations and file extension for 740 application/link-format registration. 742 Changes from ietf-02 to ietf-03: 744 o Removed 'obs' attribute definition, now defined in the CoAP 745 Observation spec (#99). 747 o Changed Resource name (n=) to Resource type (rt=) and d= to if= 748 (#121). 750 o Hierarchical organization of links under /.well-known/core 751 removed (#95). 753 o Bug in Section 3.1 on byte-wise query matching fixed (#91). 755 o Explanatory text added about alternative Web link formats (#92). 757 o Fixed a bug in Section 2.2.4 (#93). 759 o Added use case examples (#89). 761 o Clarified how the CoRE link format is used and how it differs 762 from RFC5988 (#90, #98). 764 o Changed the Interface definition format to quoted-string to 765 match the resource type. 767 o Added an IANA registry for CoRE Link Format attributes (#100). 769 Changes from ietf-01 to ietf-02: 771 o Added references to RFC5988 (#41). 773 o Removed sh and id link-extensions (#42). 775 o Defined the use of UTF-8 (#84). 777 o Changed query filter definition for any parameter (#70). 779 o Added more example, now as a separate section (#43). 781 o Mentioned cyclical links in the security section (#57). 783 o Removed the sh and id attributes, added obs and sz attributes 784 (#42). 786 o Improved the context and relation description wrt RFC5988 and 787 requested a new "hosts" default relation type (#85). 789 Changes from ietf-00 to ietf-01: 791 o Editorial changes to correct references. 793 o Formal definition for filter query string. 795 o Removed URI-reference option from "n" and "id". 797 o Added security text about multicast requests. 799 Changes from shelby-00 to ietf-00: 801 o Fixed the ABNF link-extension definitions (quotes around URIs, 802 integer definition). 804 o Clarified that filtering is optional, and the query string is to 805 be ignored if not supported (and the URL path processed as 806 normally). 808 o Required support of wildcard * processing if filtering is 809 supported. 811 o Removed the assumption of a default content-type assumption. 813 10. References 815 10.1. Normative References 817 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 818 Requirement Levels", BCP 14, RFC 2119, March 1997. 820 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 821 10646", STD 63, RFC 3629, November 2003. 823 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 824 Resource Identifier (URI): Generic Syntax", STD 66, 825 RFC 3986, January 2005. 827 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 828 Specifications: ABNF", STD 68, RFC 5234, January 2008. 830 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 832 10.2. Informative References 834 [I-D.ietf-core-coap] 835 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 836 "Constrained Application Protocol (CoAP)", 837 draft-ietf-core-coap-08 (work in progress), October 2011. 839 [REST] Fielding, R., "Architectural Styles and the Design of 840 Network-based Software Architectures", 2000, . 843 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 844 STD 13, RFC 1034, November 1987. 846 [RFC1035] Mockapetris, P., "Domain names - implementation and 847 specification", STD 13, RFC 1035, November 1987. 849 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 850 Extensions (MIME) Part One: Format of Internet Message 851 Bodies", RFC 2045, November 1996. 853 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 854 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 855 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 857 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 858 Syndication Format", RFC 4287, December 2005. 860 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 861 "Transmission of IPv6 Packets over IEEE 802.15.4 862 Networks", RFC 4944, September 2007. 864 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 865 Uniform Resource Identifiers (URIs)", RFC 5785, 866 April 2010. 868 [WADL] Hadley, M., "Web Application Description Language (WADL)", 869 2009, . 872 Author's Address 874 Zach Shelby 875 Sensinode 876 Kidekuja 2 877 Vuokatti 88600 878 FINLAND 880 Phone: +358407796297 881 Email: zach@sensinode.com