idnits 2.17.1
draft-hammer-discovery-06.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The abstract seems to contain references ([1]), which it shouldn't.
Please replace those with straight textual mentions of the documents in
question.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== The document seems to lack the recommended RFC 2119 boilerplate, even if
it appears to use RFC 2119 keywords.
(The document does seem to have the reference to RFC 2119 which the
ID-Checklist requires).
-- The document date (May 28, 2010) is 5082 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
== Missing Reference: 'TM' is mentioned on line 665, but not defined
== Outdated reference: A later version (-17) exists of
draft-hammer-hostmeta-08
** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231,
RFC 7232, RFC 7233, RFC 7234, RFC 7235)
Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group E. Hammer-Lahav
3 Internet-Draft Yahoo!
4 Intended status: Informational May 28, 2010
5 Expires: November 29, 2010
7 LRDD: Link-based Resource Descriptor Discovery
8 draft-hammer-discovery-06
10 Abstract
12 LRDD (pronounced 'lard') provides a process for obtaining information
13 about a resource identified by a Uniform Resource Identifier (URI).
14 The 'information about a resource' - a resource descriptor - provides
15 machine-readable information that aims to increase interoperability
16 and enhance interactions with the resource. LRDD provides a narrow
17 and well-defined set of rules for obtaining and processing link-based
18 descriptors (found in multiple sources such as HTTP headers, document
19 markup, and resource descriptors) which are often required for
20 security and consistent client behavior.
22 Editorial Note (to be removed by RFC Editor)
24 Please discuss this draft on the apps-discuss@ietf.org [1] mailing
25 list.
27 Status of this Memo
29 This Internet-Draft is submitted in full conformance with the
30 provisions of BCP 78 and BCP 79.
32 Internet-Drafts are working documents of the Internet Engineering
33 Task Force (IETF). Note that other groups may also distribute
34 working documents as Internet-Drafts. The list of current Internet-
35 Drafts is at http://datatracker.ietf.org/drafts/current/.
37 Internet-Drafts are draft documents valid for a maximum of six months
38 and may be updated, replaced, or obsoleted by other documents at any
39 time. It is inappropriate to use Internet-Drafts as reference
40 material or to cite them other than as "work in progress."
42 This Internet-Draft will expire on November 29, 2010.
44 Copyright Notice
46 Copyright (c) 2010 IETF Trust and the persons identified as the
47 document authors. All rights reserved.
49 This document is subject to BCP 78 and the IETF Trust's Legal
50 Provisions Relating to IETF Documents
51 (http://trustee.ietf.org/license-info) in effect on the date of
52 publication of this document. Please review these documents
53 carefully, as they describe your rights and restrictions with respect
54 to this document. Code Components extracted from this document must
55 include Simplified BSD License text as described in Section 4.e of
56 the Trust Legal Provisions and are provided without warranty as
57 described in the Simplified BSD License.
59 Table of Contents
61 1. Specification Status . . . . . . . . . . . . . . . . . . . . . 3
62 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
63 2.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4
64 2.2. Notational Conventions . . . . . . . . . . . . . . . . . . 7
65 3. Link Source Priority Order . . . . . . . . . . . . . . . . . . 7
66 4. Resource Descriptor Construction . . . . . . . . . . . . . . . 8
67 5. Link Sources . . . . . . . . . . . . . . . . . . . . . . . . . 9
68 5.1. host-meta Document . . . . . . . . . . . . . . . . . . . . 10
69 5.2. HTTP Response Headers . . . . . . . . . . . . . . . . . . 10
70 5.3. Document Markup . . . . . . . . . . . . . . . . . . . . . 11
71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12
72 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
73 7.1. The 'lrdd' Relation Type . . . . . . . . . . . . . . . . . 12
74 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13
75 Appendix B. Document History . . . . . . . . . . . . . . . . . . 13
76 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
77 8.1. Normative References . . . . . . . . . . . . . . . . . . . 15
78 8.2. Informative References . . . . . . . . . . . . . . . . . . 16
79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16
81 1. Specification Status
83 This specification was retired in favor of a single, simpler
84 document. Some of the functionality was retained merged into
85 [I-D.hammer-hostmeta] where future work is done.
87 2. Introduction
89 LRDD defines a simple process for locating resource descriptors for
90 URI-identified resources. Resource descriptors are machine-readable
91 documents that provide information about resources (resource
92 metadata) for the purposes of promoting interoperability and
93 assisting in interacting with unknown resources that support known
94 interfaces.
96 For example, a web page about an upcoming meeting can provide in its
97 descriptor the location of the meeting organizer's free/busy
98 information to potentially negotiate a different time. A social
99 network profile page descriptor can identify the location of the
100 user's address book as well as accounts on other sites. A web
101 service implementing an API with optional components can advertise
102 which of these are supported.
104 Given the wide range of metadata needs, no single descriptor format
105 or retrieval method can adequately accommodate every use case. While
106 there are many methods for obtaining resource descriptors (e.g.,
107 links, HTTP headers, WebDAV's PROPFIND [RFC4918], HTTP OPTIONS,
108 URIQA's MGET [URIQA]), LRDD utilizes the Web Linking framework
109 defined in [I-D.nottingham-http-link-header]. LRDD defines a narrow
110 profile of Web Linking for obtaining and processing link-based
111 descriptors to accommodate the common discovery needs of many Web
112 protocols.
114 In LRDD, the resource descriptor is not a single document but the
115 aggregation of links obtained from three link sources (when
116 applicable and available). The resource descriptor is constructed by
117 determining the order in which to process the three link sources and
118 aggregating the links and metadata contained in each source:
120 o host-meta document - links generated by applying the resource URI
121 to the link templates provided by the host's host-meta document as
122 defined in [I-D.hammer-hostmeta].
124 o HTTP response header - links included in the HTTP response header
125 to an HTTP [RFC2616] "HEAD" or "GET" resource representation
126 request using the "Link" header field defined in
127 [I-D.nottingham-http-link-header].
129 o Document markup - links included in the resource representation
130 markup using the element.
132 The resource descriptor also includes additional links and metadata
133 obtained from LRDD documents - XRD [OASIS.XRD-1.0] documents linked
134 to from one of the same three sources using the "lrdd" relation type.
136 The client usually looks for a link with a specific relation type or
137 other metadata. In such cases, the client does not need to construct
138 the entire resource descriptor, but instead, process the various
139 sources in their prescribed order until the desired information is
140 found. While the process described in Section 4 is meant to
141 construct the entire resource descriptor, the client MAY stop
142 processing as soon as it finds the desired information.
144 2.1. Example
146 In this example, an article published by a website allows readers to
147 post comments and provide the web address of their own blog. The
148 article page includes an avatar (a photo of the reader) when
149 displaying comments. The photo is obtained by performing discovery
150 on the web address provided by the reader, if supported by the
151 reader's blog.
153 After receiving a comment from Jane which has her own blog at
154 "http://jane.example.com/blog", the website performs LRDD discovery
155 to try and obtain Jane's photo.
157 First, the website determines the source priority order - the order
158 in which it looks for links in the various sources - for Jane's blog
159 by fetching its host-meta document from
160 "https://jane.example.com/.well-known/host-meta":
162
163
166 jane.example.com
167
169
170
171
173 which indicates the blog is using Resource-priority (giving higher
174 priority to links provided by the resource itself over those defined
175 by the global host policy). Since Jane's blog uses Resource-
176 priority, the website looks for "avatar" type links in this order:
177 elements in the blog document's markup, HTTP Link headers in
178 the blog document HTTP response, and last in the host-meta document
179 using link templates. Note that the "avatar" relation type is used
180 for illustration purposes only and at this time is not a registered
181 relation type.
183 Figure 1
185 To obtain a markup representation of Jane's blog, the website makes
186 an HTTP "GET" request to "http://jane.example.com/blog":
188 GET /blog HTTP/1.1
189 Host: jane.example.com
190 Accept: text/html
192 And receives back (HTML schema simplified for display purposes):
194 HTTP/1.1 200 OK
195 Content-Type: text/html; charset=UTF-8
196 Link: ; rel='author'
198
199
200
201
202
203
Jane's Blog
204
205
207 The document's HTML markup includes the desired link. The website
208 can fetch Jane's photo from "http://jane.example.com/image".
210 After obtaining Jane's photo, the website looks for a short
211 description of Jane to include with her comment. It performs another
212 LRDD discovery, this time looking for an "author" link.
214 Repeating the same process, the website looks for qualified
215 elements in Jane's blog HTML markup and finds none. It then looks
216 for a LRDD document - a descriptor document containing additional
217 information about the resource - which uses the "lrdd" link relation.
218 It finds none in the HTML document.
220 In Resource-priority, the next source is the HTTP header included in
221 the resource representation response. The HTTP header (shown above
222 with the HTML response) includes a qualified link to Jane's author
223 page.
225 HTTP/1.1 200 OK
226 Content-Type: text/html; charset=UTF-8
227 Link: ; rel='author'
229 Before the website can display Jane's photo and description, it needs
230 to find the copyright license used by Jane's blog. It performs
231 another LRDD discovery looking for a link with a "copyright" relation
232 type. It fails to find such link in the HTML markup as well as a
233 markup link to a LRDD document. It tries and fails to find a
234 "copyright" link in the HTTP response header or a link to a LRDD
235 document.
237 After exhausting the first two sources, the website proceeds to the
238 host-meta source (Figure 1), and looks for link templates. It fails
239 to find a link to a copyright statement, but it does find a link to a
240 LRDD document:
242
244 The website obtains the LRDD document for Jane's blog by applying the
245 blog's URI to the template:
247 http://jane.example.com?lrdd=http%3A%2F%2Fjane.example.com%2Fblog
249 and obtains the LRDD document for Jane's blog:
251
252
254 http://jane.example.com/blog
255 2.0
257
258
259 The LRDD document provided by the host-meta link template includes a
260 link to the copyright statement. The website now has all the
261 information it needs to display Jane's comment along with her photo
262 and description on the article page.
264 2.2. Notational Conventions
266 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
267 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
268 document are to be interpreted as described in [RFC2119].
270 3. Link Source Priority Order
272 The client MUST first determine the host source priority order. To
273 ensure consistent client behavior and to enable hosts to set their
274 own security policy with regard to metadata authority, LRDD provides
275 two processing profiles:
277 o Host priority - priority is given to links set by the host policy
278 (via host-meta and HTTP response headers) over those set by each
279 individual resources (via the document markup). The client MUST
280 process the three sources in the following order: host-meta
281 document, HTTP response header, and document markup.
283 o Resource priority - priority is given to the individual resource
284 over the policies of the host. The client MUST process the three
285 sources in the following order: document markup, HTTP response
286 header, and host-meta document.
288 Host priority is the default source priority order. Hosts that wish
289 to use resource priority MUST declare it by setting the LRDD priority
290 property in their host-meta document:
291 "http://lrdd.net/priority/resource". The priority property element
292 does not have a value.
294 For example:
296
297
300 example.com
301
302
304 4. Resource Descriptor Construction
306 To construct the resource descriptor, the client determines the
307 source priority order as described in Section 3, and processes each
308 of the three sources (Section 5) as follows:
310 1. Obtain and processes the source to produce an ordered list of
311 links as described for each source in Section 5.
313 2. Add any link found to the resource descriptor links list in
314 order, except for any link using the "lrdd" relation type.
316 3. For each link using the "lrdd" relation type and
317 "application/xrd+xml" media type (if present):
319 A. Obtain the LRDD document by following the scheme-specific
320 rules for the LRDD document URI. If the document URI scheme
321 is "http" or "https", the document is obtained via an HTTP
322 "GET" request to the identified URI. If the HTTP response
323 status code is 301, 302, or 307, the client MUST follow the
324 redirection response and repeat the request with the provided
325 location. If a redirection response results in another 301,
326 302, or 307 response, the client SHOULD repeat the request
327 with the provided location as many times as reasonable,
328 making sure not to enter into a loop if a location URI
329 repeats itself. The client MUST only process the document if
330 it was received with an HTTP 200 (OK) status code and is a
331 valid XRD document per [OASIS.XRD-1.0].
333 B. Add any link found in the LRDD document to the resource
334 descriptor links list in order, except for any link using the
335 "lrdd" relation type. When adding links, the client SHOULD
336 retain any extension attributes and child elements if present
337 (e.g. or elements).
339 C. Add any resource properties found in the LRDD document to the
340 resource descriptor metadata list in order (e.g. child elements of the root element).
343 For example, the resource descriptor of Jane's blog as described in
344 Section 2.1 and expressed as an XRD document (for illustration
345 purposes only) is:
347
348
350 http://jane.example.com/blog
351 2.0
353
354
355
357
358
360 Using the same example, if Jane's host-meta used host priority
361 instead of resource priority, the resource descriptor of Jane's blog
362 would be:
364
365
367 http://jane.example.com/blog
368 2.0
370
372
373
374
375
377 5. Link Sources
379 Each of the link sources supported by LRDD presents a different set
380 of requirements and benefits. The criteria used to determine which
381 sources a server supports are based on a combination of factors:
383 o The ability to offer and obtain a representation of the resource
384 by dereferencing its URI.
386 o The availability of a markup document representation supporting
387 elements compatible with [I-D.nottingham-http-link-header].
389 o The availability of an HTTP representation of the resource and the
390 ability to provide and access link information in its response
391 header.
393 o The ability to offer and process a host-meta document.
395 5.1. host-meta Document
397 The host-meta document source is available for any resource
398 identified by a URI with an authority that supports the host-meta
399 document as defined in [I-D.hammer-hostmeta]. This method does not
400 require obtaining any representation of the resource, and operates
401 solely using the resource URI.
403 Links between the resource URI and other resources are expressed
404 using link templates as defined by [I-D.hammer-hostmeta] section 3.2.
405 By applying the host-wide templates to an individual resource URI, a
406 resource-specific link is generated which can be used to express
407 links without the need to access or provide a representation for the
408 resource.
410 The client processes the host-meta document, searches for link
411 templates and applies the resource URI to produce a set of links.
412 The client MUST retain the order of links as present in the host-meta
413 document. Any links contained in the host-meta document not using
414 the "template" attribute MUST be ignored and excluded from the
415 resource descriptor (they are still valid for other purposes).
417 For example, the resource URI "http://example.com/x" and the
418 following host-meta link template:
420
422 generate an "author" link between "http://example.com/x" and
423 "http://example.com?author=http%3A%2F%2Fexample.com%2Fx".
425 5.2. HTTP Response Headers
427 The HTTP response header source is limited to resources for which an
428 HTTP "GET" or "HEAD" request returns a valid representation of the
429 resource. This source uses the "Link" header field defined in
430 [I-D.nottingham-http-link-header] and requires the retrieval of a
431 resource representation header.
433 For example:
435 Link: ;
436 rel='author'
438 The client obtains the HTTP response header links by making an HTTP
439 (or HTTPS) "GET" or "HEAD" request to the resource URI.
441 If the HTTP response status code is 301, 302, or 307, the client MUST
442 follow the redirection response and repeat the request with the
443 provided location. If a redirection response results in another 301,
444 302, or 307 response, the client SHOULD repeat the request with the
445 provided location as many times as reasonable, making sure not to
446 enter into a loop if a location URI repeats itself.
448 The client MUST only process the header if the HTTP response includes
449 a 200, 204, 206, or 304 status code. The client processes the
450 response header and searches for "Link" header fields. The client
451 MUST retain the order of links as present in the response header.
453 Link headers can include multiple relation types in a single "rel"
454 attribute (for example "rel="license copyright""). The client MUST
455 properly process such multiple relation types "rel" attributes as
456 defined by [I-D.nottingham-http-link-header].
458 5.3. Document Markup
460 The document markup source is limited to resources with an available
461 markup representation that supports typed relations using the
462 element, such as HTML [W3C.REC-html401-19991224], XHTML
463 [W3C.REC-xhtml1-20020801], and Atom [RFC4287]. Other markup formats
464 are permitted as long as the semantics of their elements are
465 fully compatible with the link framework defined in
466 [I-D.nottingham-http-link-header].
468 For example:
470
473 The client obtains the document markup by retrieving a representation
474 of the resource using the applicable transport for that resource URI.
475 When using HTTP (or HTTPS), the client obtains the document markup by
476 making a "GET" request to the resource URI.
478 If the HTTP response status code is 301, 302, or 307, the client MUST
479 follow the redirection response and repeat the request with the
480 provided location. If a redirection response results in another 301,
481 302, or 307 response, the client SHOULD repeat the request with the
482 provided location as many times as reasonable, making sure not to
483 enter into a loop if a location URI repeats itself.
485 The client MUST only process the document markup if the HTTP response
486 includes a 200 (OK) status code. The client processes the document
487 markup and searches for "LINK" elements. The client MUST retain the
488 order of links as present in the document markup.
490 The client MUST obey the document markup schema and ignore any
491 invalid elements (such as elements outside the section
492 of an HTML document). This is done to avoid unintentional markup
493 from other parts of the document to be used for discovery purposes,
494 which can have vast impact on usability and security.
496 Some elements allow multiple relation types in a single "rel"
497 attribute (for example "rel='license copyright'"). The client MUST
498 properly process such multiple relation "rel" attributes as defined
499 by the format specification.
501 6. Security Considerations
503 The methods used to perform discovery are not secure, private or
504 integrity-guaranteed, and due caution should be exercised when using
505 them. Applications that perform LRDD SHOULD consider the attack
506 vectors opened by automatically following, trusting, or otherwise
507 using links gathered from document markups, HTTP response headers, or
508 host-meta documents.
510 7. IANA Considerations
512 7.1. The 'lrdd' Relation Type
514 This specification registers the "lrdd" relation type in the Link
515 Relation Type Registry defined by [I-D.nottingham-http-link-header]:
517 Relation Name: lrdd
519 Description: Identifies a resource descriptor for the link's context
520 used by the LRDD protocol.
522 Reference: [[ This specification ]]
524 Appendix A. Acknowledgments
526 Inspiration for this memo derived from previous work on a descriptor
527 format called XRDS-Simple, which in turn derived from another
528 descriptor format, XRDS. Previous discovery workflows include Yadis
529 which is currently used by the OpenID community. While suffering
530 from significant shortcomings, Yadis was a breakthrough approach to
531 performing discovery using extremely restricted hosting environments,
532 and this memo has strived to preserve as much of that spirit as
533 possible.
535 The author wishes to thanks the OASIS XRI TC and WebFinger
536 communities for their support, encouragement, and enthusiasm for this
537 work. Special thanks go to Phil Archer, Lisa Dusseault, Joseph
538 Holsten, Mark Nottingham, John Panzer, Drummond Reed, and Jonathan
539 Rees for their invaluable feedback.
541 Appendix B. Document History
543 [[ to be removed by the RFC editor before publication as an RFC ]]
545 -06
547 o Marked as deprecated with some functionality moved to host-meta.
549 -05
551 o Many editorial changes, cleanup.
553 o Changed the processing flow to focus on a aggregation. Clients
554 can always stop when they find what they need.
556 o Clarified redirections and HTTP status codes for valid document
557 markups and response headers.
559 o Removed restrictions on multiple LRDD documents.
561 -04
563 o Changed focus to a narrow and well-defined discovery process.
565 o Removed analysis appendix and discussion of discovery types and
566 removed informative references.
568 o Expanded the descriptor definition to include links as well as
569 LRDD documents, moving away from the single-document approach.
571 o Moved the Link-Pattern field and template syntax to new host-meta
572 draft.
574 o Updated references.
576 o Added example.
578 -03
580 o Added protocol name LRDD (pronounced 'lard').
582 o Fixed Link-Pattern examples to include missing semicolons.
584 -02
586 o Changed focus from an HTTP-based process to Link-based process.
588 o Completely revised and restructured document for better clarity.
590 o Realigned the methods to produce consistent results and changed
591 the way redirections and client-errors are handled.
593 o Updated to use newer version of site-meta, now called host-meta,
594 including a new plaintext-based format to replace the previous XML
595 format.
597 o Renamed Link-Template to Link-Pattern to avoid future conflict
598 with a previously proposed Link-Template HTTP header.
600 o Removed support for the 'scheme' Link-Template parameter.
602 o Replaced restrictions with interoperability recommendations.
604 o Added IANA considerations per new host-meta registry requirements.
606 -01
608 o Rename 'resource discovery' to 'descriptor discovery'.
610 o Added informative reference to Metalink.
612 o Clarified that the resource descriptor URI can use any URI scheme,
613 not just 'http' or 'https'.
615 o Removed comment regarding redirects when using Elements.
617 o Clarified that HTTPS must be used with 'https' URIs for both Link
618 headers and host-meta retrieval.
620 o Removed DNS verification step for host-meta with schemes other
621 then 'http' and 'https'. Replaced with a general discussion of
622 authority and a security consideration comment.
624 o Organized host-meta section into another sub-section level.
626 o Enlarged the template vocabulary from a single 'uri' variable to
627 include smaller URI components.
629 o Added informative reference to RFC 2295 in analysis appendix.
631 -00
633 o Initial draft.
635 8. References
637 8.1. Normative References
639 [I-D.hammer-hostmeta]
640 Hammer-Lahav, E., "host-meta: Web Host Metadata",
641 draft-hammer-hostmeta-08 (work in progress), May 2010.
643 [I-D.nottingham-http-link-header]
644 Nottingham, M., "Web Linking",
645 draft-nottingham-http-link-header-10 (work in progress),
646 May 2010.
648 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
649 Requirement Levels", BCP 14, RFC 2119, March 1997.
651 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
652 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
653 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
655 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
656 Syndication Format", RFC 4287, December 2005.
658 [W3C.REC-html401-19991224]
659 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01
660 Specification", World Wide Web Consortium
661 Recommendation REC-html401-19991224, December 1999,
662 .
664 [W3C.REC-xhtml1-20020801]
665 Pemberton, S., "XHTML[TM] 1.0 The Extensible HyperText
666 Markup Language (Second Edition)", World Wide Web
667 Consortium Recommendation REC-xhtml1-20020801,
668 August 2002,
669 .
671 8.2. Informative References
673 [OASIS.XRD-1.0]
674 Hammer-Lahav, E. and W. Norris, "Extensible Resource
675 Descriptor (XRD) Version 1.0 (work in progress)", .
679 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
680 Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
682 [URIQA] Nokia, "The URI Query Agent Model",
683 .
685 URIs
687 [1]
689 Author's Address
691 Eran Hammer-Lahav
692 Yahoo!
694 Email: eran@hueniverse.com
695 URI: http://hueniverse.com