idnits 2.17.1 draft-snell-atompub-link-extensions-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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC4287, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC4287, updated by this document, for RFC5378 checks: 2004-07-09) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 8, 2012) is 4339 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) == Unused Reference: 'RFC1864' is defined on line 245, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group J. Snell 2 Internet-Draft June 8, 2012 3 Updates: 4287 (if approved) 4 Intended status: Standards Track 5 Expires: December 10, 2012 7 Atom Link Extensions 8 draft-snell-atompub-link-extensions-09 10 Abstract 12 This specification adds additional attributes to the Atom Syndication 13 Format link and content elements that may be used to express 14 additional metadata about linked resources. 16 Status of this Memo 18 This Internet-Draft is submitted to IETF in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on December 10, 2012. 33 Copyright Notice 35 Copyright (c) 2012 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 52 3. Hash Attributes . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3.1. Computing Hash Digests . . . . . . . . . . . . . . . . . . 3 54 3.2. The 'hash' attributes . . . . . . . . . . . . . . . . . . . 4 55 4. The 'etag' attribute . . . . . . . . . . . . . . . . . . . . . 4 56 5. The 'modified' attribute . . . . . . . . . . . . . . . . . . . 5 57 6. The 'accessed' attribute . . . . . . . . . . . . . . . . . . . 5 58 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 59 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 60 9. Normative References . . . . . . . . . . . . . . . . . . . . . 7 61 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 1. Introduction 65 This specification adds additional attribute to the Atom Syndication 66 Format [RFC4287] link and content elements that may be used to 67 express additional metadata about linked resources most specifically 68 for the purpose of allowing a consuming application to detect whether 69 a linked resource has potentially been modified since the link was 70 established or whether the content of the linked resource has been 71 correctly fetched as a result of dereferencing the link. 73 2. Notational Conventions 75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 77 document are to be interpreted as described in BCP 14, [RFC2119]. 79 This specification uses XML Namespaces [W3C.REC-xml-names-19990114] 80 to uniquely identify XML element names. It uses the following 81 namespace prefix for the indicated namespace URI; 83 "atom": "http://www.w3.org/2005/Atom" 85 3. Hash Attributes 87 Hash digest values are computed by the producers of Atom documents 88 and are representative of the state of linked resources at a given 89 point in time. The intent of providing hash values is to allow 90 consumers of the Atom document to later determine if linked resource 91 have been modified since the document was produced. There are, 92 however, many factors that determine whether a consumer of a document 93 will be capable of calculating a digest value identical to that 94 specified in a hash attribute. Accordingly, hash attribute values 95 MUST be considered to be strictly advisory. User agents SHOULD 96 notify users when matching hash digest values cannot be computed but 97 MUST NOT stop processing or signal an error. 99 3.1. Computing Hash Digests 101 When the resource referenced by atom:link or atom:content elements is 102 retrievable using HTTP, hash digest values are computed by first 103 performing an HTTP GET request on the URL specified by the @href or 104 @src attributes, extracting the returned entity-body, then following 105 the steps specified in Section 14.15 of [RFC2616]. 107 3.2. The 'hash' attributes 109 The 'hash' Attribute specifies a whitespace-delimited list of hash 110 digest values calculated over the resource identified by the atom: 111 link/@href or atom:content/@src attributes. Each digest value is 112 represented as a token identifying the hash algorithm and the hex- 113 encoded digest separated by an ASCII colon (":"). The 'hash' 114 attribute MAY appear as a child of the atom:link and atom:content 115 elements. 117 hash = attribute hash { digest-list } 118 digest-list = digest-value *( LWSP digest-value ) 119 digest-value = token ":" 1*HEXDIG 121 An example MD5 and SHA-256 digest of an enclosed MP3 file: 123 128 This specification defines the following hash algorithm tokens: 129 "md2", "md5", "sha-1", "sha-224", "sha-256", "sha-384", and "sha- 130 512". Additional hash algorithms MAY be used. 132 4. The 'etag' attribute 134 The 'etag' Attribute specifies an Entity Tag [RFC2616] for the 135 resource identified by the atom:link or atom:content element as 136 provided by the server hosting the resource. The 'etag' attribute 137 MAY appear as a child of the atom:link and atom:content elements. 139 etag = attribute etag { entity-tag } 141 entity-tag = [ weak ] opaque-tag 142 weak = "W/" 143 opaque-tag = quoted-string 144 quoted-string = ( <"> *(qdtext | quoted-pair ) <"> ) 145 qdtext = > 146 quoted-pair = "\" CHAR 148 An example weak entity tag for an enclosed MP3 file: 150 154 Note that HTTP defines the Entity Tag production such that quotes are 155 significant. For example, the values "W/xyzzy" and W/"xyzzy" 156 represent two distinctly different Entity Tags, the former being 157 considered a "strong" entity tag, the latter a "weak" entity tag. 158 The etag attribute value MUST include the appropriate double 159 quotation marks. 161 The presence and placement of the quotes in the entity tag value can 162 introduce some difficulty when inserting the value into the etag 163 attribute. Producers of Atom documents must either use single quotes 164 when specifying the value of the etag attribute, e.g. 165 etag='W/"xyzzy"' or use the " entity reference to escape the 166 double quotes within the etag value, e.g. etag="W/"xyzzy"". 167 A strong entity tag would be encoded as either etag='"xyzzy"' or 168 etag=""xyzzy"". 170 5. The 'modified' attribute 172 The 'modified' Attribute specifies the date and time when the 173 resource identified by the atom:link or atom:content element was last 174 modified. The value MUST conform to the "date-time" production 175 defined by [RFC3339]. An uppercase "T" character MUST be used to 176 separate date and time, and an uppercase "Z" character MUST be 177 present in the absence of a numeric time zone offset. The 'modified' 178 attribute MAY appear as a child of the atom:link and atom:content 179 elements. 181 modified = attribute modified { xsd:dateTime } 183 An example last-modified attribute for an enclosed MP3 file: 185 189 6. The 'accessed' attribute 191 The 'accessed' Attribute specifies the most recent date and time when 192 the resource identified by the atom:link or atom:content element was 193 accessed by the producer of the Atom document. The value MUST 194 conform to the "date-time" production defined by [RFC3339]. An 195 uppercase "T" character MUST be used to separate date and time, and 196 an uppercase "Z" character MUST be present in the absence of a 197 numeric time zone offset. The 'accessed' attribute MAY appear as a 198 child of the atom:link and atom:content elements. 200 accessed = attribute accessed { xsd:dateTime } 202 An example accessed attribute for an enclosed MP3 file: 204 208 The intent of the 'accessed' attribute is to allow the Atom document 209 producer to establish an explicit point-in-time at which additional 210 metadata about the linked resource was established. For instance, if 211 the 'accessed' attribute is used, a consuming user agent can assume 212 that any hash attribute values, entity tags and modified timestamps 213 were valid at the date and time specified by the 'accessed' 214 attributes value. If the 'accessed' attribute is not specified, 215 consumers SHOULD use the value of the atom:updated element to 216 determine the point-in-time at which the link metadata was considered 217 to be valid. 219 7. Security Considerations 221 The 'hash', 'etag' and 'modified' attributes are intended to allow an 222 Atom publisher the means of describing the state of a linked resource 223 at a point-in-time -- usually at the moment specified by the 224 'accessed' attribute or at the moment specified by the atom:updated 225 element. An Atom consumer that is aware of these attributes can use 226 their values as an integrity check to determine if the linked 227 resource has been modified since the attribute values were 228 established by the publisher. 230 The 'hash' attribute is intended for use when the publisher of an 231 Atom document requires the ability to link to a specific version of a 232 resource that is expected to remain stable and unchanged for a useful 233 period of time. If publishers fall into the habit of regularly 234 including hash digests for resources whose states change frequently, 235 there is a danger that consumers of feeds containing large numbers of 236 invalid digests will simply begin to ignore them and completely 237 undermine the utility of the attribute. 239 8. IANA Considerations 241 No IANA actions are required by this document. 243 9. Normative References 245 [RFC1864] Myers, J. and M. Rose, "The Content-MD5 Header Field", 246 RFC 1864, October 1995. 248 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 249 Requirement Levels", BCP 14, RFC 2119, March 1997. 251 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 252 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 253 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 255 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 256 Internet: Timestamps", RFC 3339, July 2002. 258 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 259 Syndication Format", RFC 4287, December 2005. 261 [W3C.REC-xml-names-19990114] 262 Hollander, D., Bray, T., and A. Layman, "Namespaces in 263 XML", World Wide Web Consortium FirstEdition REC-xml- 264 names-19990114, January 1999, 265 . 267 Author's Address 269 James M Snell 271 Email: jasnell@us.ibm.com 272 URI: http://ibm.com