--- 1/draft-ietf-atompub-protocol-00.txt 2006-02-04 22:42:00.000000000 +0100 +++ 2/draft-ietf-atompub-protocol-01.txt 2006-02-04 22:42:00.000000000 +0100 @@ -1,19 +1,19 @@ Network Working Group J. Gregorio, Ed. Internet-Draft BitWorking, Inc Expires: December 30, 2004 R. Sayre, Ed. Boswijck Memex Consulting July 1, 2004 The Atom Publishing Protocol - draft-ietf-atompub-protocol-00.txt + draft-ietf-atompub-protocol-01.txt Status of this Memo By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that @@ -39,84 +39,87 @@ Abstract This memo presents a protocol for using XML (Extensible Markup Language) and HTTP (HyperText Transport Protocol) to edit content. The Atom Publishing Protocol is an application-level protocol for publishing and editing Web resources belonging to periodically updated websites. The protocol at its core is the HTTP transport of Atom-formatted representations. The Atom format is documented in the - Atom Syndication Format 0.3 PRE-DRAFT - (http://www.mnot.net/drafts/draft-nottingham-atom-format-02.html). + Atom Syndication Format (draft-ietf-atompub-format-00.txt). - To provide feedback on this Internet-Draft, join the atom-syntax - mailing list (http://www.imc.org/atom-syntax/index.html). +Editorial Note + + To provide feedback on this Internet-Draft, join the + . Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1 Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 2. The Atom Publishing Protocol Model . . . . . . . . . . . . . 4 3. Functional Specification . . . . . . . . . . . . . . . . . . 5 3.1 PostURI . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.1 Locating the PostURI . . . . . . . . . . . . . . . . . 5 3.1.2 Request . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.3 Response . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 EditURI . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.1 Locating . . . . . . . . . . . . . . . . . . . . . . . 7 3.2.2 Request . . . . . . . . . . . . . . . . . . . . . . . 7 - 3.3 FeedURI . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 3.3.1 Locating . . . . . . . . . . . . . . . . . . . . . . . 8 - 3.3.2 Request . . . . . . . . . . . . . . . . . . . . . . . 8 - 3.3.3 Response . . . . . . . . . . . . . . . . . . . . . . . 8 - 3.4 Link Tag . . . . . . . . . . . . . . . . . . . . . . . . . 8 - 3.4.1 rel . . . . . . . . . . . . . . . . . . . . . . . . . 8 - 3.4.2 href . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 3.4.3 title . . . . . . . . . . . . . . . . . . . . . . . . 9 - 3.4.4 type . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 3.5 Atom Request and Response Body Constraints . . . . . . . . 9 - 3.5.1 id . . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 3.5.2 link . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 3.5.3 title . . . . . . . . . . . . . . . . . . . . . . . . 10 - 3.5.4 summary . . . . . . . . . . . . . . . . . . . . . . . 10 - 3.5.5 content . . . . . . . . . . . . . . . . . . . . . . . 10 - 3.5.6 issued . . . . . . . . . . . . . . . . . . . . . . . . 11 - 3.5.7 modified . . . . . . . . . . . . . . . . . . . . . . . 11 - 3.5.8 created . . . . . . . . . . . . . . . . . . . . . . . 11 - 3.5.9 author . . . . . . . . . . . . . . . . . . . . . . . . 11 - 3.5.10 contributor . . . . . . . . . . . . . . . . . . . . 12 - 3.5.11 generator . . . . . . . . . . . . . . . . . . . . . 12 - 4. Security Considerations . . . . . . . . . . . . . . . . . . 12 - 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 13 - 6. Appendix A - SOAP Enabling . . . . . . . . . . . . . . . . . 13 - 6.1 Servers . . . . . . . . . . . . . . . . . . . . . . . . . 13 - 6.2 Clients . . . . . . . . . . . . . . . . . . . . . . . . . 13 - 7. Appendix B - Examples . . . . . . . . . . . . . . . . . . . 13 - 7.1 Example for a weblog . . . . . . . . . . . . . . . . . . . 13 - 7.2 Example for a wiki . . . . . . . . . . . . . . . . . . . . 13 - 8. Revision History . . . . . . . . . . . . . . . . . . . . . . 14 - 9. Normative References . . . . . . . . . . . . . . . . . . . . 15 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 15 - Intellectual Property and Copyright Statements . . . . . . . 16 + 3.3 FeedURI . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 3.3.1 Locating . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.3.2 Request . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.3.3 Response . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.4 Link Tag . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.4.1 rel . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 3.4.2 href . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 3.4.3 title . . . . . . . . . . . . . . . . . . . . . . . . 10 + 3.4.4 type . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 3.5 Atom Request and Response Body Constraints . . . . . . . . 11 + 3.5.1 id . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 3.5.2 link . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 3.5.3 title . . . . . . . . . . . . . . . . . . . . . . . . 11 + 3.5.4 summary . . . . . . . . . . . . . . . . . . . . . . . 11 + 3.5.5 content . . . . . . . . . . . . . . . . . . . . . . . 12 + 3.5.6 issued . . . . . . . . . . . . . . . . . . . . . . . . 12 + 3.5.7 modified . . . . . . . . . . . . . . . . . . . . . . . 12 + 3.5.8 created . . . . . . . . . . . . . . . . . . . . . . . 12 + 3.5.9 author . . . . . . . . . . . . . . . . . . . . . . . . 13 + 3.5.10 contributor . . . . . . . . . . . . . . . . . . . . 13 + 3.5.11 generator . . . . . . . . . . . . . . . . . . . . . 13 + 3.6 Securing the Atom Protocol . . . . . . . . . . . . . . . . 13 + 3.6.1 [@@TBD@@ CGI Authentication] . . . . . . . . . . . . . 14 + 4. Security Considerations . . . . . . . . . . . . . . . . . . 14 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 14 + 6. Appendix A - SOAP Enabling . . . . . . . . . . . . . . . . . 15 + 6.1 Servers . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 6.2 Clients . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 7. Appendix B - Examples . . . . . . . . . . . . . . . . . . . 15 + 7.1 Example for a weblog . . . . . . . . . . . . . . . . . . . 15 + 7.2 Example for a wiki . . . . . . . . . . . . . . . . . . . . 15 + 8. Revision History . . . . . . . . . . . . . . . . . . . . . . 15 + 9. Normative References . . . . . . . . . . . . . . . . . . . . 17 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 17 + Intellectual Property and Copyright Statements . . . . . . . 19 1. Introduction The Atom Publishing Protocol is an application-level protocol for - publishing and editing Web resources. + publishing and editing Web resources using HTTP [RFC2616] and XML. 1.1 Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", the and "OPTIONAL" in - this document are to be interpreted as described in RFC2119. + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. 1.2 Terminology Atom Entry: An Atom Entry is a fragment of a full Atom feed. In this case, the fragment is a single 'entry' element and all its child elements. Each Atom Entry describes a single Web resource, providing metadata and optionally a textual representation of that resource. PostURI: A URI that is used to create new resources. POSTing an Atom Entry to this URI will create a new resource. @@ -183,22 +186,22 @@ href="URI for Posting goes here" title="The name of the site."> 3.1.2 Request The request contains a filled-in Atom entry, subject to the constraints in section Section 3.5. 3.1.3 Response - The possible status codes from a POST are 201, 303, 400, 401, 404, - 410 and 500. + The possible status codes from a POST are 201, 303, 400, 404, 410 and + 500. 3.1.3.1 Response code 201 Response includes a Location: header with the URI of the created resource, i.e. the URI used to edit the entry, as opposed to the URI used to display the content. The body of the response will contain the entry "filled-in" with time stamps and any other data the server chooses to reveal. This must contain enough information to enable a client to issue a subsequent PUT to this location. Note that the server may chose to omit the content in the response, particularly if @@ -206,32 +209,32 @@ 3.1.3.2 Response code 303 The body of this response does not contain the filled-in Entry, but the filled-in Entry can be found under a different URI and can be retrieved using a GET method on that resource. The URI SHOULD be given by the Location field in the response. 3.1.3.3 Response code 400 - Indicates that the server believes that that data sent constitutes an - invalid request. A short description of the error will appear on the - - itself. A longer description will appear in the body. + Indicates that the server believes that the data sent constitutes an + invalid request. As an example, the data posted may not be + well-formed XML. The server SHOULD include an entity containing an + explanation of the error situation, and whether it is a temporary or + permanent condition. 3.1.3.4 Response code 500 Indicates that the server detected an internal error on the server - processing this request (such as an unhandled exception). A short - description of the error will appear on the - - itself. A longer description will appear in the body. + processing this request (such as an unhandled exception). The server + SHOULD include an entity containing an explanation of the error + situation, and whether it is a temporary or permanent condition. 3.2 EditURI An EditURI is used to edit a single entry. Each entry that is editable MUST have a unique URI. This URI supports both GET and PUT and they are used in tandem for an editing cycle. The client GETs the representation which is formatted as an Atom entry. The client may then update the entry and then PUT it back to the same URI. The PUT will cause all the related resources to be updated, for example, the HTML representation. @@ -262,40 +265,99 @@ title="Readable desc of the entry."> Note: The critical characteristic of this link tag is the @rel of 'service.edit' and the @type of 'application/atom+xml'. 3.2.2 Request A PUT request, and a GET response both contain a filled-in Atom entry, subject to the constraints in section Section 3.5. + The expected status codes from a GET are 200, 301, 307, and 500. + 400, 404, and 410 are also possible. + + The expected status codes from a PUT are 2xx, 301, 307, 500 and 501. + 400, 404, and 410 are also possible. + +3.2.2.1 Successful Requests + + Servers MUST indicate successful GET requests with a 200 response. + + Servers MUST indicate successful PUT requests with a 2xx response. + Servers MAY include additional information in the PUT response. + Clients SHOULD NOT expect any additional information in a PUT + response. + +3.2.2.2 Response code 301 + + The entry has moved permanently, the new URI is given in the Location + header. The client SHOULD retry the GET using the URI returned in + the Location header. When a PUT operation is attempted the user + agent should prompt the user before attempting the PUT on the URI + returned in the Location header. + +3.2.2.3 Response code 307 + + The entry has moved temporarily, the new URI is given in the Location + header. The client SHOULD retry the GET using the URI returned in + the Location header. When a PUT operation is attempted the user + agent should prompt the user before attempting the PUT on the URI + returned in the Location header. + +3.2.2.4 Response code 401 + + Indicates that the server believes that the data sent constitutes an + invalid request. As an example, the data posted may not be + well-formed XML. The server SHOULD include an entity containing an + explanation of the error situation, and whether it is a temporary or + permanent condition. + +3.2.2.5 Response code 410 + + Indicates that the requested resource is gone permanently. The + client SHOULD NOT repeat the request again. + +3.2.2.6 Response code 500 + + Indicates that the server detected an internal error on the server + processing this request (such as an unhandled exception). The server + SHOULD include an entity containing an explanation of the error + situation, and whether it is a temporary or permanent condition. + 3.3 FeedURI The FeedURI is used to retrieve a representation in Atom format. Note that this feed is different from a typical Atom feed in that it contains "link" elements for navigating and manipulating the content of the site. For example there should be a "link" element with rel="next" whose URI points to the next block of entries on the site. Similarly, the feed element can contain a "link" element with rel="service.post", the URI of which is a PostURI. Individual entries should contain "link" elements with rel="service.edit" whose URIs are EditURIs. + This document only uses some of the methods available for each type + of URI. For example, the only method described by this document for + the FeedURI is GET. Any other method may be supported by the URI + types described, but defining their behavior is beyond the scope of + this document. In this light you may notice that the PostURI only + supports the POST method. It is possible, and allowable, that for + some implementations the PostURI and the FeedURI are the same URI. + @@ Editor's Note: @@ Note that the "service.feed" takes the place of the Introspection File and the Search facet in previous versions of the specification. That is, facet discovery, which was previously done by inspecting the Introspection file is now done by looking for "link" tags with an attribute "rel" set to "service.[something]" in the "service.feed" file. At the same time the same representation replaces the search facet by having "link" tags that point to other - feeds using well knows 'rel' attribute values such as 'next' and + feeds using well-known 'rel' attribute values such as 'next' and 'prev', or the search can branch in multiple directions by specifying multiple link tags with rel="service.feed" and having differing title attributes that announce the kind of search results in that feed. 3.3.1 Locating A link tag of the following format points to the FeedURI. appears in the 'head' of the document. The 'head' section only allows a linear list of 'link' tags. The Atom format allows 'link' tags as children @@ -497,36 +562,64 @@ 3.5.11 generator PostURI MUST be present and contain a URI. The value of the element indicates the code base used to create this request. MUST also have an attribute 'version' with a version number. FeedURI MUST NOT be present. EditURI GET MUST NOT be present. PUT MUST NOT be present. +3.6 Securing the Atom Protocol + + All instances of publishing Atom entries SHOULD be protected by + authentication to prevent posting or editing by unknown sources. + Atom servers and clients MUST support one of the following + authentication mechanisms, and SHOULD support both. + + o HTTP Digest Authentication [RFC2617] + o [@@TBD@@ CGI Authentication ref] + + Atom servers and clients MAY support encryption of the Atom session + using TLS [RFC2246]. + + There are cases where an authentication mechanism may not be + required, such as a publicly editable Wiki, or when using the PostURI + to post comments to a site that does not require authentication to + create comments. + +3.6.1 [@@TBD@@ CGI Authentication] + + This authentication method is included as part of the protocol to + allow Atom servers and clients that cannot use HTTP Digest + Authentication but where the user can both insert its own HTTP + headers and create a CGI program to authenticate entries to the + server. This scenario is common in environments where the user + cannot control what services the server employs, but the user can + write their own HTTP services. + 4. Security Considerations Because Atom is a publishing protocol, it is important that only - authorized users can create and edit entries. The security of Atom - is based on HTTP Digest Authentication and/or the WSSE-style - authentication described in this document. Any weaknesses in either - of these two protocols will obviously affect the security of the Atom - publishing protocol. + authorized users can create and edit entries. - Both HTTP Digest Authentication and the WSSE-style authentication - described in this document are susceptible to dictionary-based - attacks on the shared secret. If the shared secret is a password - (instead of a random string with sufficient entropy), an attacker can - determine the secret by exhaustively comparing the authenticating - string with hashed results of the public string and dictionary - entries. + The security of Atom is based on HTTP Digest Authentication and/or + [@@TBD@@ CGI Authentication]. Any weaknesses in either of these + authentication schemes will obviously affect the security of the Atom + Publishing Protocol. + + Both HTTP Digest Authentication and [@@TBD@@ CGI Authentication] are + susceptible to dictionary-based attacks on the shared secret. If the + shared secret is a password (instead of a random string with + sufficient entropy), an attacker can determine the secret by + exhaustively comparing the authenticating string with hashed results + of the public string and dictionary entries. See RFC 2617 for more detailed description of the security properties of HTTP Digest Authentication. @@TBD@@ Talk here about using HTTP basic and digest authentication. @@TBD@@ Talk here about denial of service attacks using large XML files, or the billion laughs DTD attack. 5. IANA Considerations @@ -573,20 +666,27 @@ the 'introspection' file. 1. Creating a new entry 2. Finding an old entry 3. editing an old entry 4. commenting on a entry (via HTML and Atom) 7.2 Example for a wiki Fill this in like above but for a wiki. 8. Revision History + draft-ietf-atompub-protocol-01 - Added in sections on Responses for + the EditURI. Allow 2xx for response to EditURI PUTs. Elided all + mentions of WSSE. Started adding in some normative references. + Added the section "Securing the Atom Protocol". Clarified that it is + possible that the PostURI and FeedURI could be the same URI. Cleaned + up descriptions for Response codes 400 and 500. + Rev draft-ietf-atompub-protocol-00 - 5Jul2004 - Renamed the file and re-titled the document to conform to IETF submission guidelines. Changed MIME type to match the one selected for the Atom format. Numerous typographical fixes. We used to have two 'Introduction' sections. One of them was moved into the Abstract the other absorbed the Scope section. IPR and copyright notifications were added. Rev 09 - 10Dec2003 - Added the section on SOAP enabled clients and servers. @@ -629,22 +729,34 @@ changed to application/atom+xml. Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more commonly used format: draft-gregorio-NN.html. Renamed all references to URL to URI. Broke out introspection into it's own section. Added the Revision History section. Added more to the warning that the example URIs are not normative. 9 Normative References - [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, - June 1999. + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", + RFC 2246, January 1999. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., + Leach, P., Luotonen, A. and L. Stewart, "HTTP + Authentication: Basic and Digest Access Authentication", + RFC 2617, June 1999. Authors' Addresses Joe Gregorio (editor) BitWorking, Inc 1002 Heathwood Dairy Rd. Apex, NC 27502 US Phone: +1 919 272 3764